webMethods Broker Client Java API Programmer’s Guidedocshare02.docshare.tips/files/23632/236321526.pdf · webMethods Broker Client Java API Programmer’s Guide Version 8.2 3 Table

Title Page

webMethods Broker Client Java APIProgrammer’s Guide

Version 8.2

April 2011

Copyright& Docu-ment ID
This document applies to webMethods Broker Version 8.2 and to all subsequent releases.

Specifications contained herein are subject to change and these changes will be reported in subsequent release notes or new editions.

Copyright © 2001–2011 Software AG, Darmstadt, Germany and/or Software AG USA, Inc., Reston, VA, United States of America, and/or their licensors.

Detailed information on trademarks and patents owned by Software AG and/or its subsidiaries is located at http://documentation.softwareag.com/legal/.

Use of this software is subject to adherence to Software AG's licensing conditions and terms. These terms are part of the product documentation, located at http://documentation.softwareag.com/legal/ and/or in the root installation directory of the licensed product(s).

This software may include portions of third-party products. For third-party copyright notices and license terms, please refer to “License Texts, Copyright Notices and Disclaimers of Third-Party Products”. This document is part of the product documentation, located at http://documentation.softwareag.com/legal/and/or in the root installation directory of the licensed product(s).

Document ID: BR-CLIENTJAVAAPI-PG-82SP1-20110401

http://documentation.softwareag.com/legal/



Table of Contents

About this Guide . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25Document Conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25Documentation Installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26Online Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26

1. Getting Started . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30Event-Based Applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30

Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31Broker Clients . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31The Broker . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32Broker-to-Broker Communication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32

Using the webMethods Broker Java API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33Application Development with webMethods Broker . . . . . . . . . . . . . . . . . . . . . . . . . . . 33Application Deployment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34

webMethods Broker Java API Online Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34

2. Using Broker Clients . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38Understanding Broker Clients . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38

Client State . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38Client Groups . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39

Client Life Cycle . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39Queue Storage Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39

Client Infoset . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40Creating and Destroying Broker Clients . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40

Client Identifiers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42Assigning Client Identifiers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42Obtaining Client Identifiers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42Hard-coding Client Identifiers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42

Destroying a Broker Client . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43Using Several Broker Clients . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43

Disconnecting and Reconnecting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43Disconnecting a Broker Client . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44Reconnecting a Broker Client . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44

Using the newOrReconnect Method . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45Connection Notification . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46

Defining a Callback Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46Registering the Callback Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46Un-Registering Callback Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47

Obtaining Client State and Status . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47

webMethods Broker Client Java API Programmer’s Guide Version 8.2 3

Basic Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47Client Queue Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48

Advanced Features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48Connection Settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48

Client Time-out Settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48Platform Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49Broker Territory and Broker-to-Broker Communication . . . . . . . . . . . . . . . . . . . . . 49

Broker Connection Descriptors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49Creating Connection Descriptors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50Obtaining a Client's Connection Descriptor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50

Converting to String . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50Automatic Re-connection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51

Using Automatic Re-connection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51Rules for Automatic Re-connection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51

Using Client Keep-Alive . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52Setting the Keep-Alive Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52Getting the Current Keep-Alive Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53Using the Keep-Alive Feature with a Shared Connection . . . . . . . . . . . . . . . . . . . 54

Sharing Connections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54Sharing Client State . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54

Event Processing with Shared Client State . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55By-Publisher Event Ordering . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55Event Processing without Ordering . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56When is Sharing State Useful? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56State Sharing Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56Calling Sequence for Sharing Client State . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56

Priority Ordering for Broker Queues . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57Priority Ordering and Performance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57

Using Security Features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58Redelivery Counting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58

3. Using the Callback Model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60Understanding Callbacks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60

Using Callbacks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60Implementing a Callback . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61Passing Arguments to Callback Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61

General Callback Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62Using General Callbacks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62

Specific Callback Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63Using Specific Callbacks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63

Dispatching Callback Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64Using dispatch . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64Using mainLoop . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65Using threadedCallbacks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65

4 webMethods Broker Client Java API Programmer’s Guide Version 8.2

Event Dispatching Rules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65

4. Creating and Initializing Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68Event Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68

Event Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68Event Type Cache . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69Event Type Names . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69Event Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70Event Identifier . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70

Creating Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70General Event Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71Field Type Checking . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71Converting Events as Binary Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72Restoring Events from Binary Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72

Event Data Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72Field Data Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72Obtaining Field Names . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73

Regular Data Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73Setting Regular Data Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73Getting Regular Field Values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74

Sequence Data Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75Setting Sequence Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76Getting Sequence Field Values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77

Structure Data Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78Setting Structure Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78

Setting a Struct Field from an Event . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78Setting a Struct Sequence Field from an Event . . . . . . . . . . . . . . . . . . . . . . . . . . 79

Getting Structure Field Values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79Getting a Struct Field as an Event . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79Getting a Struct Sequence Field . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79

Envelope Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80Read-only Envelope Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82

The connectionIntegrity Envelope Field . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84The pubNetAddr Envelope Field . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85The route Envelope Field . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85

Specifying Field Names . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86

5. Subscribing to and Receiving Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90Event Subscriptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90

Limits on Subscriptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91Subscribing to Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91

Uniqueness of Subscriptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91Cancelling a Subscription . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92


Using Wildcards . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92Receiving Events in the Get-Events Model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93

Getting Multiple Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93Synchronous Get Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94Detecting Redelivered Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95

Manual Redelivery Counting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 96Automatic Redelivery Counting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97

Redelivery and Older Versions of webMethods Software . . . . . . . . . . . . . . . . . . . . . . . 98Subscription Identifiers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99

Specifying Subscription IDs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99Obtaining Subscription Identifiers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100Generating Subscription Identifiers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100

BrokerSubscription Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101Getting Events using the poll Method . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101

The BrokerClientPoll Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102Key Methods used in the Polling Model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102Using the poll Method . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102

A Polling Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103Detecting Deadletters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104

Creating a Deadletter Subscription . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104Deadletter Subscriptions and Filters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 105Deadletter Permissions and Persistence . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 105

How Deadletter Subscriptions Relate to Regular Subscriptions . . . . . . . . . . . . . . 105Deadletter Behavior in a Territory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 105

6. Using Request-Reply . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 108The Request-Reply Model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 108

Request Events and the Tag Field . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 108Getting and Setting the Tag . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109

Using the trackId Field . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109Reply Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109

Determining a Reply Event's Type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109The Requestor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 110

Using the Get-event Approach . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111Callbacks with Tags . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112Using publishRequestAndWait . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113

The Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114Checking Subscription and Publishing Permissions . . . . . . . . . . . . . . . . . . . . . . . . . . . 115Processing Request Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 116Delivering Replies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117

Delivering Acknowledgment Replies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117Delivering Error Replies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117Delivering Null Replies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 118Delivering One or More Reply Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 118


Delivering Partial Replies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 118

7. Transaction Semantics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122About Transactional Client Processing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122

About the BrokerTransactionalClient Class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122Transaction Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122

Using Broker Transaction Clients . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123Obtaining an External Transaction ID . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 124Beginning a Transaction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 124Operating within a Transaction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 124

Publishing a Transaction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125Publishing Multiple Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125Delivering a Transaction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 126Getting Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 126

Preparing Transactions For Commit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 127Ending a Transaction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 127

Committing a Transaction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 128Aborting a Transaction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 128

Destroying the Transactional Client . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 128Creating a Transactional Client . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 129

8. Publishing and Delivering Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131Publishing Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132

Limits on Publication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132Publishing an Event . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 133Publishing Multiple Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 133

Delivering Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 133Obtaining the Client Identifier . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 134Delivering an Event . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 134Delivering Multiple Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 135

9. Handling Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 137Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 138BrokerExceptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 138

Catching Exceptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 138Determining the Exception Type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 138Getting an Exception Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 139

Setting the System Diagnostic Level . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 139

10. Using BrokerDate Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 141Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 142Date and Time Representation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 142BrokerDate Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 142


11. Using Sequence Numbers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 145Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 146Sequence Numbers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 146Publisher Sequence Numbers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 146

Using Publisher Sequence Numbers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 147Maintaining Publish Sequence Number State . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 147

Receipt Sequence Numbers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 147Default Acknowledgment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 148Default Acknowledgment With Callbacks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 148Explicitly Acknowledging Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 148Maintaining Receipt Sequence Number State . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 149Other Considerations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 149

12. Managing Event Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 151Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 152Event Type Definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 152

Obtaining Event Type Names . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 152Obtaining Event Type Definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 153Obtaining Event Field Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 153

Obtaining Event Type Descriptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 153Obtaining Storage Type Property . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 153Obtaining the Time-to-live Property . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 154Obtaining Type Definitions as Strings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 154

Obtaining Broker Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 154Broker Territory and Broker-to-Broker Communication . . . . . . . . . . . . . . . . . . . . . 155

Event Type Definition Cache . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 155Notification of Event Type Definition Changes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 155Locking the Type Definition Cache . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 155

Infosets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 156

13. Using Event Filters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 157Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 158Filter Strings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 158

Specifying Filter Strings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 158Locale Considerations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 159Filter Rules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 159Field Names . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 159Filter Operators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 160

Logical Filter Operators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 160Comparison Filter Operators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 160Arithmetic Filter Operators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 161Bitwise Operators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 161String Operators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 161

Operator Precedence . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 162Using Regular Expressions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 163


Using Hints . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 163Filter Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 164

charAt . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 164contains . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 164date . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 165date . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 165endsWith . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 165regexpMatch . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 166startsWith . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 166substring . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 166toDouble . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 167toInt . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 167toLong . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 167toLowerCase . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 167toString . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 168toUpperCase . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 168toUpperCase . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 168

Using Filters with Subscriptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 169Using BrokerFilters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 169

Obtaining Filter Strings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 170Obtaining Event Type Names . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 170Converting Broker Filters to Strings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 171

14. Load Balancing and Failover for Publish Operations . . . . . . . . . . . . . . . . . . . . . . . . . . 173Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 174Understanding Clustering . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 174

BrokerClusterPublishers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 175Monitoring Territory Activity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 175Executing Publish/Deliver Operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 175

Load Balancing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 175Publishers and Subscribers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 175

Failover . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 176Using BrokerClusterPublisher . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 176

Creating and Destroying BrokerClusterPublisher . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 176Creating a BrokerClientPublisher . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 177

Client Identifiers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 178Obtaining Client Identifiers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 178Destroying a BrokerClusterPublisher . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 178Disconnecting and Reconnecting BrokerClusterPublisher . . . . . . . . . . . . . . . . . . . . . . 179Disconnecting a BrokerClusterPublisher . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 179Reconnecting a BrokerClusterPublisher . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 179Using the newOrReconnect method . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 180

Broker Cluster Publisher Connection Notification . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 181Defining a Connection Callback Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 181Registering the Connection Callback Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 181


Canceling the Connection Callback Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 182Broker Cluster Publisher Selection Notification . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 182

Defining a Selection Callback Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 183Registering the Selection Callback Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 183Canceling the Selection Callback Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 183

Obtaining BrokerClusterPublisher Status . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 185Publishing and Delivering Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 185

Creating a New BrokerEvent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 186Field Type Checking . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 186Publishing Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 187Publishing an Event . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 187Publishing Multiple Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 188Delivering Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 189Delivering an Event . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 189Delivering Multiple Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 190Request-Reply Model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 190Using publishRequestAndWait . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 190Include-Exclude Brokers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 191

15. Working with Basic Authentication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 193Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 194Basic Authentication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 194Configuring the Broker Java Client for Basic Authentication . . . . . . . . . . . . . . . . . . . . . . . . 194

Configuring Basic Authentication by using BrokerConnectionDescriptor Class . . . . . . 194Configuring Basic Authentication by Using System Properties . . . . . . . . . . . . . . . . . . . 195

16. Working with SSL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 197Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 198Broker SSL Security . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 198Certificate Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 198Configuring the Broker Java Client for SSL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 199

Configuring SSL Using the BrokerConnectionDescriptor Class . . . . . . . . . . . . . . . . . . 199Configuring SSL by Using the System Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . 201Setting Encryption . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 201Retrieving a Broker Server's Certificate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 202Enabling FIPS in Java Clients . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 202

17. Java API Client Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 203BrokerCallback . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 203

handleBrokerEvent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 204BrokerClient . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 204

Constants . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 204Constructor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 206

BrokerClient . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 206Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 209

acknowledge Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 209


acknowledge . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 209acknowledge . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 209acknowledgeThrough . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 210

begin Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 210beginAdapterTransaction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 210beginTransaction (deprecated) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 211

can Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 212canPublish . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 212canSubscribe . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 212

cancel Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 213cancelCallbackForSubId . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 213cancelCallbackForTag . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 213cancelCallbacks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 214cancelCheckForEvents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 214cancelSubscription . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 214cancelSubscription . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 215cancelSubscriptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 215

check Method . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 216checkForEvents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 216

clear Method . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 217clearQueue . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 217

create Method . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 217createClientQueueBrowser . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 217

deliver Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 218deliver . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 218deliver . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 219deliverAckReplyEvent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 220deliverErrorReplyEvent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 220deliverNullReplyEvent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 221deliverPartialReplyEvents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 222deliverReplyEvent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 224deliverReplyEvents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 224deliverRequestAndWait . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 225deliverWithAck . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 226

destroy Method . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 228destroy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 228

disconnect Method . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 228disconnect . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 228

dispatch Method . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 229dispatch . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 229

does Method . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 230doesSubscriptionExist . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 230

end Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 230endAdapterTransaction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 230endTransaction (deprecated) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 231


finalize Method . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 232finalize . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 232

get Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 232getAccessLabel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 232getApiVersionNumber . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 232getApplicationName . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 232getBrokerHost . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 233getBrokerName . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 233getBrokerPort . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 233getBrokerSSLCertificate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 233getBrokerVersionNumber . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 234getCanPublishNames . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 234getCanPublishTypeDefs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 234getCanSubscribeNames . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 234getCanSubscribeTypeDefs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 235getClientGroup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 235getClientId . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 235getClientInfoset . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 235getClientSSLEncryptionLevel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 236getConnectionDescriptor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 236getDefaultBrokerPort . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 236getEvent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 236getEvents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 238getEvents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 239getEventTypeDef . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 240getEventTypeDefs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 241getEventTypeInfoset . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 241getEventTypeInfosetNames . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 242getEventTypeInfosets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 243getEventTypeNames . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 243getEventTypeNames . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 244getLastPublishSequenceNumber . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 244getPlatformInfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 244getPlatformInfoKeys . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 245getQueueLength . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 245getRetrievedStatus . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 246getRetrievedSessionID . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 246getScopeNames . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 246getStateShareLimit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 246getSubscriptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 247getTerritoryName . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 247

increment Method . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 247incrementRedeliveryCount . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 247

interrupt Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 248interruptDispatch . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 248


interruptGetEvents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 248interruptCheckForEvents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 248

is Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 249isClientPending . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 249isConnected . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 249isPending . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 249

main Method . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 250mainLoop . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 250

make Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 250makeSubId . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 250makeTag . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 250makeTransactionId . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 251makeUniqueSubId . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 251

negative Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 251negativeAcknowledge . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 251negativeAcknowledge . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 252

new Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 253newOrReconnect . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 253newSubscription . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 254newSubscription . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 255newSubscription . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 257newSubscriptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 257

poll Method . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 258poll . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 258

prime Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 259prime . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 259primeAllClients . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 260

publish Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 260publish . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 260publish . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 261publishRequestAndWait . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 261publishWithAck . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 262

reconnect Method . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 264reconnect . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 264

register Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 266registerCallback . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 266registerCallbackForSubId . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 266registerCallbackForTag . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 267registerConnectionCallback . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 268

resend Method . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 269resendUnacknowledgedEvents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 269

set Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 270setAutomaticControlLabel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 270setClientInfoset . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 270setDefaultClientTimeout . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 270


setPlatformInfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 271setStateShareLimit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 271

stop Method . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 272stopMainLoop . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 272

threaded Method . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 272threadedCallbacks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 272

to Method . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 273toString . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 273

BrokerClientPoll . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 273Constants . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 273Constructors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 274

BrokerClientPoll . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 274Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 275

getBrokerClient . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 275getData . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 275getReady . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 275getRequested . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 275isReady . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 276isRequested . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 276setData . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 276

BrokerClusterPublisher . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 277Constructor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 277

BrokerClusterPublisher . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 277Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 278

cancelConnectionCallback . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 278cancelSelectionCallback . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 279canPublish . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 279deliver . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 279deliver . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 280deliverRequestAndWait . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 281destroy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 282disconnect . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 282excludeBroker . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 283getApplicationName . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 283getCanPublishNames . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 283getClientGroup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 284getClientId . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 284getClusterPublisherInfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 284getClusterPublisherStats . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 284getLastUsed . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 285getMonitorClientId . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 285getTerritoryName . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 286includeBroker . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 286isConnected . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 286localPublish . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 286


localPublish . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 287localPublishRequestAndWait . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 288newOrReconnect . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 288publish . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 290publish . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 291publishRequestAndWait . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 291reconnect . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 292registerConnectionCallback . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 294registerSelectionCallback . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 294toString . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 295

BrokerConnectionCallback . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 295Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 295

handleConnectionChange . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 295BrokerConnectionDescriptor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 296

Constants . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 297Constructor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 298

BrokerConnectionDescriptor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 298BrokerConnectionDescriptor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 298

Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 298getAccessLabelHint . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 298getAuthUserName . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 299getAutomaticReconnect . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 299getAutomaticRedeliveryCount . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 299getConnectionShare . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 299getConnectionShareLimit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 299getForcedReconnect . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 300getKeepAlivePeriod . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 300getKeepAliveResponseTime . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 300getKeepAliveRetryCount . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 301getRedeliveryCountEnabled . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 301getSharedEventOrdering . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 301getSSLCertificate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 302getSSLCertificateDns . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 303getSSLCertificateFile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 303getSSLCipherSuites . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 304getSSLDistinguishedName . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 304getSSLEncrypted . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 304getSSLEncryptionLevel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 304getSSLKeystore . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 305getSSLKeystoreType . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 305getSSLKeystoreType . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 305getSSLProvider . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 305getSSLTruststoreType . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 305getSSLRootDns . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 305getStateShare . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 306


setAccessLabelHint . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 306setAuthInfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 306setAutomaticReconnect . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 307setAutomaticRedeliveryCount . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 307setConnectionShare . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 307setConnectionShareLimit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 308setForcedReconnect . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 308setKeepAlive . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 308setRedeliveryCountEnabled . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 310setSharedEventOrdering . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 310setSSLCertificate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 311setSSLCipherSuites . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 312setSSLEncrypted . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 312setSSLProvider . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 312setSSLKeystore . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 313setSSLKeystoreType . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 313setSSLTruststore . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 313setSSLTruststoreType . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 313setStateShare . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 313toString . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 313

BrokerCPConnectionCallback . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 314Method . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 314

handleConnectionChange . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 314BrokerCPSelectionCallback . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 314

Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 315chooseClusterClient . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 315chooseClusterClient . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 315

BrokerDate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 316Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 316Constructors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 316

BrokerDate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 316BrokerDate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 316BrokerDate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 317BrokerDate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 317BrokerDate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 317BrokerDate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 317BrokerDate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 317BrokerDate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 318

Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 319clear . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 319clearTime . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 319compareTo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 319equals . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 319getJavaCalendar . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 319getJavaDate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 320


parseDate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 320parseLocalizedDate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 321setDate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 321setDateTime . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 322setJavaCalendar . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 322setJavaDate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 323setTime . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 323toLocalizedString . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 323toString . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 323toString . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 324

BrokerEvent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 324Constants . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 324Constructors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 325

BrokerEvent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 325BrokerEvent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 326BrokerEvent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 327BrokerEvent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 328

Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 329clear . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 329clearField . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 329clearModificationFlag . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 330fromBinData . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 330fromObject . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 331get<type>Field . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 331get<type>SeqField . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 333getBaseTypeName . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 334getBooleanField . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 335getBooleanSeqField . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 335getByteField . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 335getByteSeqField . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 335getCharField . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 335getCharSeqField . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 335getClient . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 335getDateField . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 335getDateSeqField . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 335getDoubleField . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 335getDoubleSeqField . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 335getEventId . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 335getField . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 336getFieldNames . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 336getFieldType . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 337getFloatField . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 338getFloatSeqField . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 338getIntegerField . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 338getIntegerSeqField . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 338


getLongField . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 338getLongSeqField . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 338getPriority . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 338getPublishSequenceNumber . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 338getReceiptSequenceNumber . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 339getScopeTypeName . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 339getSequenceField . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 339getSequenceFieldSize . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 340getShortField . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 341getShortSeqField . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 341getStorageObject . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 341getStringField . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 341getStringSeqField . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 341getStructFieldAsEvent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 341getStructSeqFieldAsEvents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 342getSubscriptionIds . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 343getRedeliveryCount . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 343getTag . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 344getTypeDef . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 344getTypeName . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 344getUCCharField . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 344getUCCharSeqField . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 344getUCStringField . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 345getUCStringSeqField . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 345hasBeenModified . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 345isAckReply . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 345isErrorReply . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 345isFieldSet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 345isLastReply . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 346isNullReply . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 346set<type>Field . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 346set<type>SeqField . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 348setBooleanField . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 349setBooleanSeqField . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 349setByteField . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 349setByteSeqField . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 350setCharField . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 350setCharSeqField . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 350setDateField . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 350setDateSeqField . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 350setDoubleField . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 350setDoubleSeqField . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 350setField . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 350setField . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 351setFloatField . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 352


setFloatSeqField . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 353setIntegerField . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 353setIntegerSeqField . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 353setLongField . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 353setLongSeqField . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 353setModificationFlag . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 353setPriority . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 353setPublishSequenceNumber . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 353setSequenceField . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 354setSequenceFieldSize . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 356setShortField . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 356setShortSeqField . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 357setStringField . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 357setStringFieldToSubstring . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 357setStringSeqField . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 357setStructFieldFromEvent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 358setStructSeqFieldFromEvents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 358setTag . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 359setUCCharField . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 359setUCCharSeqField . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 360setUCStringField . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 360setUCStringFieldToSubstring . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 360setUCStringSeqField . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 361stringFromANSI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 361stringToANSI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 361toBinData . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 361toFormattedString . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 361toFormattedString . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 362toLocalizedFormattedString . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 362toLocalizedString . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 362toObject . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 363toString . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 363toString . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 363toString . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 364toString . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 364validate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 364

BrokerException . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 365Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 365

getCode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 365getDiagnostics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 365getMessage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 365getMinorCode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 366setDiagnostics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 366toCompleteString . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 366toString . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 366


BrokerField . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 367Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 367

type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 367value . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 367

Constructors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 367BrokerField . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 367BrokerField . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 367

BrokerFilter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 367Constructors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 368

BrokerFilter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 368BrokerFilter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 368

Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 369getEventTypeName . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 369getFilterString . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 369match . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 369toString . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 370

BrokerFormat . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 370Specifying Field Names and Formats . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 370Format options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 371Constructor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 371

BrokerFormat . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 371Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 372

assemble . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 372assemble . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 372assemble . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 373format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 373format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 373format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 373format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 374format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 374formatBindVariable . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 375getTokenCount . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 375getTokenValue . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 375isReferenceToken . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 376preparse . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 376setFormatMode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 376

BrokerMonitorClient . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 377Constructors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 377

BrokerMonitorClient . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 377Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 378

destroy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 378getHostName . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 378getPort . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 378getServerLogEntries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 378getServerLogStatus . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 379


getServerRunStatus . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 379getServers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 379getVersion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 379getVersionNumber . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 379pruneMonitorLog . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 380reloadConfig . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 380reloadConfigForServer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 380startServer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 380toString . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 381

BrokerSSLCertificate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 381Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 381

begin_date . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 381distinguished_name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 381end_date . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 381issuer_distinguished_name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 381status . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 382

Constructors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 382BrokerSSLCertificate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 382BrokerSSLCertificate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 382

BrokerSubscription . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 382Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 383

event_type_name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 383filter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 383sub_id . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 383

Constructors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 383BrokerSubscription . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 383BrokerSubscription . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 383BrokerSubscription . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 384

Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 384toString . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 384

BrokerTransactionalClient . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 384Constructors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 385

BrokerTransactionalClient . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 385Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 386

abort . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 386abortAll . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 386acknowledge . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 387acknowledge . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 387acknowledgeThrough . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 388beginTransaction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 388commit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 389commitAll . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 389deliver . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 390deliver . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 390deliverAckReplyEvent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 391


deliverErrorReplyEvent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 392deliverNullReplyEvent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 392deliverPartialReplyEvents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 393deliverReplyEvent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 394deliverReplyEvents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 394deliverWithAck . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 395getEvent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 395getEvents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 396getEvents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 397getExternalId . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 397getId . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 398getState . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 398getXAResource . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 398interruptGetEvents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 398newOrReconnect . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 398newOrReconnectTransactionalClient . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 399prepare . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 400prepare . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 401prepareAll . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 401prepareAll . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 402publish . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 402publish . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 403publishWithAck . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 403reconnect . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 404reconnectTransactionalClient . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 405setId . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 406

BrokerTypeCache . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 406Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 406

flushCache . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 406lockCache . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 407unlockCache . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 407

BrokerTypeDef . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 407Constants . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 407Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 408

getBaseTypeName . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 408getBrokerHost . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 408getBrokerName . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 409getBrokerPort . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 409getDescription . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 409getFieldDef . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 409getFieldNames . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 410getFieldType . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 410getScopeTypeName . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 411getStorageType . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 411getTerritoryName . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 411


getTimeToLive . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 411getTypeName . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 412toString . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 412toString . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 412

A. API Exceptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 413

B. Parameter Naming Rules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 419Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 420Length Restriction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 420Restricted Characters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 420Reserved Words . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 421

EventType and Infoset Names . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 421System Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 421webMethods Broker Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 421



About this Guide

The webMethods Broker Client Java API Programmer’s Guide describes the application programming interfaces (API) that you use to create event-based applications with the Java language.

This document is intended for use by programmers who are developing event-based applications using webMethods Broker. The reader is assumed to possess general knowledge of programming and specific knowledge of the Java programming language.

This book assumes you are familiar with the terminology and basic operations of your operating system (OS). If you are not, please refer to the appropriate documentation for that OS.

Document Conventions

Convention Description

Bold Identifies elements on a screen.

Narrowfont Identifies storage locations for services on webMethods Integration Server, using the convention folder.subfolder:service.

UPPERCASE Identifies keyboard keys. Keys you must press simultaneously are joined with a plus sign (+).

Italic Identifies variables for which you must supply values specific to your own situation or environment. Identifies new terms the first time they occur in the text.

Monospace font Identifies text you must type or messages displayed by the system.

{ } Indicates a set of choices from which you must choose one. Type only the information inside the curly braces. Do not type the { } symbols.

| Separates two mutually exclusive choices in a syntax line. Type one of these choices. Do not type the | symbol.

[ ] Indicates one or more options. Type only the information inside the square brackets. Do not type the [ ] symbols.

... Indicates that you can type multiple options of the same type. Type only the information. Do not type the ellipsis (...).


About this Guide

Documentation Installation

You can download the product documentation using the Software AG Installer. Depending on the release of the webMethods product suite, the location of the downloaded documentation will be as shown in the table below.

Online Information

You can find additional information about Software AG products at the locations listed below.

Note: The Empower Product Support Web site and the Software AG Documentation Web site replace Software AG ServLine24 and webMethods Advantage.

For webMethods... The documentation is downloaded to...

6.x The installation directory of each product.

7.x A central directory named _documentation in the main installation directory (webMethods by default).

8.x A central directory named _documentation in the main installation directory (Software AG by default).

If you want to... Go to...

Access the latest version of product documentation.

Software AG Documentation Web site

http://documentation.softwareag.com


http://documentation.softwareag.com

About this Guide

Find information about product releases and tools that you can use to resolve problems.

See the Knowledge Center to:

Read technical articles and papers.

Download fixes and service packs.

Learn about critical alerts.

See the Products area to:

Download products.

Download certified samples.

Get information about product availability.

Access older versions of product documentation.

Submit feature/enhancement requests.

Empower Product Support Web site

https://empower.softwareag.com

Access additional articles, demos, and tutorials.

Obtain technical information, useful resources, and online discussion forums, moderated by Software AG professionals, to help you do more with Software AG technology.

Use the online discussion forums to exchange best practices and chat with other experts.

Expand your knowledge about product documentation, code samples, articles, online seminars, and tutorials.

Link to external Web sites that discuss open standards and many Web technology topics.

See how other customers are streamlining their operations with technology from Software AG.

Software AG Developer Community for webMethods

http://communities.softwareag.com/

If you want to... Go to...


https://empower.softwareag.com/KnowledgeCenter/default.asp

https://empower.softwareag.com/Products/default.asp

https://empower.softwareag.com

http://communities.softwareag.com/

About this Guide


1 Getting Started

Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30

Event-Based Applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30

Using the webMethods Broker Java API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33

webMethods Broker Java API Online Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34


1 Getting Started

Overview

This chapter describes the basic features of the Java language API for the webMethods Broker system, and how to use it to build event-based client programs that communicate with each other and with other applications through Broker.

Event-Based Applications

The webMethods Broker system provides you with interfaces, classes, and methods for building powerful, event-based applications that are made up of de-coupled client programs. The client programs are de-coupled because they communicate by sending and receiving events through a third entity called a Broker. A Broker is actually part of a Broker Server, which can contain multiple Brokers. For more information on the Broker Server, see Administering webMethods Broker.

The figure below depicts a simple example where an Order Entry program receives input from a customer and publishes a CustOrder event. The act of publishing the event causes the event to be sent to the Broker. The Broker then determines that the Order Database program has subscribed to the CustOrder event, and so the Broker distributes the event to the Order Database client program.

Sending events through a Broker

More complex applications are possible than the simple example shown in the next figure. The Order Database program could generate an OrderConfirmed event that would be sent to the Order Entry program as a reply to a CustOrder event.

Two clients implementing a request-reply event mode

You might also design a system where several client programs receive the CustOrder event and perform their own processing, such as checking the inventory on hand or verifying the customer's credit status.


1 Getting Started

Multiple clients subscribing to an event type

The webMethods Broker system also allows the Broker and the client programs that comprise an application to execute on different hosts within a network.

Events

Events are one of the most important ingredients in an application developed with the webMethods Broker system. Events are defined using Software AG Designer, described in Software AG Designer Online Help.

Note: Please note that Broker events are generally called documents in Designer and other webMethods components.

Events have these important characteristics:

Events are organized into event scopes, allowing you to group the events related to your application.

Events have a unique event type, which defines the event fields they contain and the data type associated with each field.

Event fields represent data in a platform-independent representation, allowing clients on different platforms to exchange information.

Events are discussed in greater detail in “Creating and Initializing Events” on page 67.

Broker Clients

Client programs can consist of one or more Broker clients. Just as a program can open and use more than one file, a program can create and use multiple Broker clients. After created, a Broker client represents a connection to a particular Broker on a particular host.


1 Getting Started

A Broker client can subscribe to events, publish events, and receive events. Broker clients can also share a connection to a Broker and they can also share the same client queue and client state. Broker clients are covered in greater detail in Using Clients.

The Broker

The webMethods Broker coordinates the exchange of events between client programs. To accomplish this complex task, the Broker:

Queues all events that are published by Broker clients.

Sends events to those clients which have subscribed to and are ready to receive the event.

Provides various levels of reliable delivery of events through the use of event sequence numbers. Sequence numbers are described in “Using Sequence Numbers” on page 145.

Provides event filtering services that allow Broker clients to selectively filter the events they will receive, based on event content. Filters are discussed in “Using Event Filters” on page 157.

Maintains information on all event type definitions, which are defined with Designer. See the Software AG Designer Online Help for more information.

Note: Broker events are known as Broker document types in Designer.

Maintains information about client groups, which define event publication permissions, event subscription permissions, network access control, and client event queue characteristics for Broker clients in each group. See Administering webMethods Broker for details on client groups.

Maintains an event queue and client state information for each Broker client that has been created.

Maintains a dead letter queue, in which it retains events for which it has no subscribers.

Broker-to-Broker Communication

The webMethods Broker systems allows two or more Brokers to share information about their event type definitions and client groups. This sharing of information enables communication between Broker clients connected to different Brokers. The next figure shows how an event published by a client program connected to Broker_1 can be received by a client program connected to either Broker_1, Broker_2, or Broker_3.


1 Getting Started

Broker-to-Broker communication

In order to share information and forward events, Brokers must join a territory. All Brokers within the same territory have knowledge of one another's event type definitions and client groups. For more information on this feature, see Administering webMethods Broker.

Using the webMethods Broker Java API

The webMethods Broker Java API is implemented as a Java package that provides all the necessary interfaces, classes and methods for:

Creating and manipulating events.

Transferring events to a Broker.

Retrieving events from a Broker.

Querying the Broker for state information.

You can use the webMethods Broker Java API to create a wide variety of applications, including simple clients, watchdog agents, and adapters for legacy applications and existing data sources.

Application Development with webMethods Broker

Using the webMethods Broker system to develop applications involves the following steps:

1 Install the webMethods Broker system. See Installing webMethods Products or your system administrator.

2 Start the Broker. See Installing webMethods Products or your system administrator.

3 Design the client programs and the events that will comprise your system.


1 Getting Started

4 Use Designer to define the events for your application. See the Software AG Designer Online Help or your system administrator.


5 Ensure that your applications can locate the webMethods Broker Java package. You can do this by using one of the following techniques:

a Compile your application with the -classpath complier flag set to the location of the webMethods Broker Java package. This is the recommended technique.

b Install the webMethods Broker Java package in the same directory where you develop your applications. You must also ensure that your CLASSPATH environment variable includes the current directory specification.

c Add the location of the webMethods Broker Java package to your CLASSPATH environment variable. This is not recommended due to potential name conflicts with other Java packages that might be installed on your system.

6 Write and compile your client code.

7 Execute your client programs.

Application Deployment

When deploying your Java client applications, you must also deploy the necessary webMethods Broker classes. The webMethods Broker installation contains an archive with all of the files necessary for application deployment.

Note: This file must be in the application's CLASSPATH when the application is deployed.

webMethods Broker Java API Online Documentation

The webMethods Broker Java API provides an API-level documentation generated by the Sun javadoc application. The documentation is available as HTML web pages, in the following platform-specific location.

Platform Location

AIX, HP-UX, Linux, and Solaris

Software AG_directory/common/lib/wm-brokerclient.jar

Software AG_directory/common/lib/wm-g11nutils.jar

Windows Software AG_directory\common\lib\wm-brokerclient.jar

Software AG_directory\common\lib\wm-g11nutils.jar


1 Getting Started

Platform Location of webMethods Broker Java Packages

AIX, HP-UX, Linux, and Solaris

Software AG_directory/broker/doc/java_api/index.html

Windows Software AG_directory\broker\doc\java_api\index.html


1 Getting Started


2 Using Broker Clients

Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38

Understanding Broker Clients . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38

Creating and Destroying Broker Clients . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40

Disconnecting and Reconnecting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43

Connection Notification . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46

Obtaining Client State and Status . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47

Advanced Features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48

Broker Connection Descriptors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49



Overview

This chapter describes the webMethods Broker Java API for creating, using, and destroying Broker clients in your applications. Reading this chapter should help you understand:

How to create and use a BrokerClient object.

The context associated with a BrokerClient, including client identifiers, client state, client groups, client life cycle, event queue storage types, and client infoset.

How to disconnect and reconnect a BrokerClient.

How to register callback methods for connection notification.

BrokerConnectionDescriptor objects and their role in the sharing of client state and client connections between multiple Broker clients.

How to use the BrokerConnectionDescriptor to enable automatic re-connection.

How to use the BrokerConnectionDescriptor to enable the redelivery counting feature.

How to use the BrokerConnectionDescriptor to enable the keep-alive feature.

Understanding Broker Clients

A client program creates one or more Broker clients in order to publish or retrieve events. For example, a network monitoring application might create a Broker client to publish events that represent network transmission errors. A network management application might create a Broker client to subscribe to these network error events. If the number of network error events retrieved reaches a critical threshold, the management application might create a different Broker client and use it to publish statistics about the network failure.

Event-based client applications are de-coupled from one another because they generate and receive events through an entity called a Broker Server. When your client program creates a Broker client, it is actually establishing a connection between your application and a Broker running on the local host or some host on the network.

Client State

When a connection is established between your Broker client and a Broker, the Broker creates and maintains a client state that includes the following information:

A client identifier that uniquely identifies your Broker client to a particular Broker.

A queue where events received for your Broker client will be stored until they are retrieved.

A list of event subscriptions for your Broker client.

The client group with which your Broker client is associated.



A single client state be shared by multiple Broker clients, as described in “Sharing Client State” on page 54.

Client Groups

Every Broker client belongs to a client group, which provides important security features by limiting the behavior of the member Broker clients. Client groups are defined and maintained by your webMethods Broker administrator. Each client group is given a name. The restrictions on client group names are discussed in “Parameter Naming Rules” on page 419.

Client groups define these important limits:

The event types that be published or delivered by the group members.

The event types that be delivered to group members and for which they register subscriptions. See “Event Subscriptions” on page 90 for more information.

The client life cycle, or how long the Broker will maintain client state information for each group member.

The client queue type, which determines how the events are stored by the Broker.

Security information that determines which entities create a Broker client in this group.

Client Life Cycle

The life cycle associated with your Broker client's client group will determine how long the Broker will maintain the client state for your Broker client.

If the life cycle is explicit-destroy, the client state can only be destroyed by a system administrator or by your client application calling the BrokerClient.destroy method. The explicit-destroy life cycle is useful for client applications that need to maintain state information even if a network or system failure occurs.

If the life cycle is destroy-on-disconnect, the Broker will destroy the client state whenever the connection between the Broker client and the Broker is lost. The destroy-on-disconnect life cycle is used by client applications that do not need to maintain state information in the event of a network or system failure.

Queue Storage Types

The client queue storage type, also defined by your Broker client's client group, can be either volatile or guaranteed.



Note: Storage types also be defined for a particular event type. See “Obtaining Storage Type Property” on page 153 for information on how client group and event type storage specifications interact.

Client Infoset

Each BrokerClient is allowed to store information about its state or configuration in a single client infoset. The BrokerClient.getClientInfoset method allows you to obtain the infoset for a particular BrokerClient. The setClientInfoset method allows you to set the infoset for a particular BrokerClient. For convenience, the client infoset is treated by both of these methods as a BrokerEvent.

Creating and Destroying Broker Clients

Creating a BrokerClient will establish a connection between your application and a Broker. This connection is identified by the following tuple:

The name of the host where the Broker is executing.

The IP port number assigned to the Broker.

The name of the Broker.

Multiple Broker clients within a single application that connect to the same Broker will all share a single network connection, as described in “Sharing Connections” on page 54.

Your application can create a Broker client by calling the BrokerClient constructor and specifying these parameters:

The name of the host where the Broker to which you want to connect is executing.

The name of the Broker to which you want to connect. You specify a null value if you want to connect to the default Broker. The default Broker for a particular host is determined by your webMethods Broker administrator.

Queue Type Description

volatile The Broker will queue events for your Broker client using local memory. This offers higher performance along with a greater risk of losing events if a hardware, software, or network failure occurs.

guaranteed The Broker will use a two-phase commit process to queue events for your Broker client. This offers the lowest performance, but very little risk of losing events if a hardware, software, or network failure occurs.



A unique client ID that identifies your Broker client. You can specify a null value if you want the Broker to generate a unique client ID for you. The client ID generated by the Broker can be obtained after this call completes by calling the BrokerClient.getClientId method.

The client group for your new Broker client. Client groups define the event types your new Broker client will be able to publish or retrieve, as well as the life cycle and queue storage type for your Broker client. Client groups are defined by your webMethods Broker administrator.

The name of the application that is creating the Broker client. This name is used primarily by webMethods Broker administration and analysis tools. The application name can be any meaningful string of characters you choose.

A BrokerConnectionDescriptor to be used for the new Broker client. If you specify a null value, a new connection descriptor will be created for you. The BrokerConnectionDescriptor class is covered in detail in “Broker Connection Descriptors” on page 49.

The following example is from a sample application that shows the creation of a new BrokerClient object. In this example, a null Broker name is passed to indicate that the caller wants to connect to the default Broker on the host "localhost."

Note: See “Parameter Naming Rules” on page 419 for restrictions on Broker names.

A null client ID is specified, indicating that the Broker should generate a unique client ID. A client group named "default" is requested and the application name is set to "Publish Sample #1." A null connection descriptor is passed, indicating that the caller wants a default connection to be established.

import COM.activesw.api.client.*; class publish1 {

static String broker_host = "localhost"; static String broker_name = null; static String client_group = "default"; . . .

public static void main(String args[]) {

BrokerClient c; . . . /* Create a client */ try {

c = new BrokerClient(broker_host, broker_name, null, client_group, "Publish Sample #1",null);

} catch (BrokerException ex) { System.out.println("Error on create client\n"+ex);

return; }

. . .



Client Identifiers

The client identifier is a string that uniquely identifies your Broker client. The client identifier is used to:

Identify the Broker client that published an event, described in “Read-only Envelope Fields” on page 82.

Identify the recipient of a delivered event, described in “Delivering Events” on page 133.

Re-connect a previously disconnected BrokerClient, described on “Disconnecting and Reconnecting” on page 43.

Allow two or more Broker clients connected to the same Broker to share the same client state, described on “Sharing Client State” on page 54.

Note: A client identifier cannot start with a '# 'character, nor can it contain '/' or '@' characters. See “Parameter Naming Rules” on page 419 for complete details.

Assigning Client Identifiers

It is always best to let the Broker assign a unique client identifier at the time you create your Broker client. You then retrieve your client identifier by calling the BrokerClient.getClientId method.

Obtaining Client Identifiers

The best way to obtain another Broker client's identifier is by retrieving the pubId envelope field from an event published by that client, as described in “Obtaining the Client Identifier” on page 134.

Hard-coding Client Identifiers

In some cases, you have a compelling reason to hard-code a client identifier into your application or to accept the client identifier as a command-line argument:

1 If your Broker client is designed to be disconnected and reconnected over multiple sessions and needs to preserve the client identifier, you might want to hard-code the client identifier.

2 If your application cooperates with other applications that need to know your client identifier, you can choose to hard-code the client identifier into each of the cooperating applications. If the applications are connected to different Brokers in a multi-Broker environment, you must hard-code the fully-qualified client identifier by adding the name of the Broker to which the client is connected to the client identifier, as shown in the table below.

Unqualified and fully qualified client identifiers



Destroying a Broker Client

The following example shows the use of the destroy method. When a BrokerClient is destroyed, its event queue and all other client state information will also be destroyed.

. . . BrokerClient c; . . . try {

c.destroy(); } catch (BrokerException ex) {

System.out.println("Error on client destroy\n"+ex); return;

} . . .

Using Several Broker Clients

You might find that a number of programming situations are made easier by creating several Broker clients within a single application.

If your application has several phases of operation, you can use a separate client to represent each phase.

Because different Broker clients can belong to distinct client groups, they can subscribe to and publish different event types. You can use this feature to divide the work your application needs to perform.

A multi-threaded application can spawn separate threads for each Broker client, which can result in a cleaner programming model.

Disconnecting and Reconnecting

The webMethods Broker API allows you to disconnect a Broker client from a Broker without actually destroying the Broker client. This is only useful if your Broker client's life cycle is explicit-destroy because the client state for the Broker client and all queued events is preserved by the Broker. Any events received by the Broker for your Broker client while it was disconnected will remain in the Broker client's event queue. When your Broker client reconnects to the Broker, specifying the same client ID, it can continue retrieving events from the event queue. Disconnecting and reconnecting can be particularly useful for applications that want to do batch-style processing at scheduled intervals.

Client Unqualified Client ID Client's Broker Name Fully Qualified Client ID

Joe 1000 Denver //Denver/1000

Mary 1001 Denver //Denver/1001

Chuck 1000 Chicago //Chicago/1000



Disconnecting a Broker Client

You disconnect your Broker client by calling the BrokerClient.disconnect method, as shown in the following example. If the Broker client's life cycle is destroy-on-disconnect, the client state and event queue storage will be destroyed by the Broker. If the Broker client's life cycle is explicit-destroy, the client state and event queue storage will be preserved by the Broker until the Broker client reconnects.

. . . BrokerClient c; . . . try {

c.disconnect(); } catch (BrokerException ex) {

System.out.println("Error on client disconnect\n"+ex); return;

} . . .

Reconnecting a Broker Client

You can reconnect a previously disconnected Broker client that has a life cycle of explicit-destroy by calling the BrokerClient.reconnect method and specifying the same client ID that was used when your client was last connected, as shown in the following example. If the Broker client's life cycle is explicit-destroy, the client state and event queue storage will have been preserved by the Broker since previous call to BrokerClient.disconnect was made.

Note: “Automatic Re-connection” on page 51 describes how you can enable automatic re-connection for your Broker client in the event the connection to the Broker is lost.

static String broker_host = "localhost"; static String broker_name = null; static String client_group = "default"; . . . public static void main(String args[]) {

BrokerClient c; String client_id; . . . /* Create a client */ try {


} catch (BrokerException ex) { . . .

} /* Save the client ID */ client_id = c.getClientId(); . . . /* Disconnect the client */ try {




. . . } . . . /* Reconnect the client with the same client_id */ try {

c = BrokerClient.reconnect(broker_host, broker_name, client_id, null);


} . . .

Using the newOrReconnect Method

You might find it convenient to use the BrokerClient.newOrReconnect method to create or reconnect a client when your client application is expected to be executed repeatedly. The newOrReconnect method shown in the following example, attempts to create a new Broker client. If the client already exists and was simply disconnected, it will be reconnected.

static String broker_host = "localhost"; static String broker_name = null; static String client_group = "default"; public static void main(String args[]) {

BrokerClient c; String client_id; . . . client_id = “123”; /* The first time this program is executed, a Broker client * will be created. Subsequent executions will simply reconnect * the Broker client. */ try {

c = BrokerClient.newOrReconnect(broker_host, broker_name, null, client_group, "Publish Sample #1",null);


} /* Do some processing */ . . . /* Disconnect the client */ try {


. . . } . . .



Connection Notification

The connection notification feature allows you to register a callback method for a particular Broker client that will be invoked if the client is disconnected from the Broker. The connection notification feature can be particularly useful if your Broker client is using the automatic reconnect feature and needs to know when it has been reconnected to the Broker.

Note: Connection callback methods do not have a global scope. They must be registered separately for each Broker client that wants to use this feature.

Defining a Callback Object

You use the BrokerConnectionCallback interface to derive your own callback object. Your implementation must provide an implementation of the handleConnectionChange callback method. You can implement this method to recreate any needed client state that have been lost or to provide other methods, such as logging of error messages.

Registering the Callback Object

You use the BrokerClient.registerConnectionCallback method to register a method you want to be called in the event your Broker client is disconnected or reconnected to its Broker. This method accepts two parameters. The first parameter is the BrokerConnectionCallback-derived object that implements your callback method. The second parameter is a client_data object, which is used to pass any needed data to the callback method.

Note: Any callback objects previously registered for a Broker client will be replaced by the one currently being registered.

When the BrokerConnectionCallback object's the callback method is invoked, that method's connect_state parameter will be set to one of the BrokerClient-defined values shown in the following table.



Connect state values

Un-Registering Callback Objects

You can un-register a callback by invoking the BrokerClient.registerConnectionCallback method with a null callback object.

Obtaining Client State and Status

There are a variety of methods you can use to obtain state and status information about a Broker client.

Basic Properties

Use the BrokerClient.getBrokerVersionNumber method to obtain the Broker's version number.

Use the BrokerClient.doesSubscriptionExist method to obtain the name of the application associated with a Broker client.

Use the BrokerClient.getBrokerHost method to obtain the name of the host where the Broker that is associated with a Broker client is executing.

Use the BrokerClient.getBrokerName method to obtain the name of the Broker to which a Broker client is connected.

Use the BrokerClient.getBrokerPort method to obtain the IP port number of the Broker to which a Broker client is connected.

Use the BrokerClient.getClientGroup method to obtain the name of the client group with which a Broker client is associated.

Use the BrokerClient.getClientId method to obtain the a Broker client's client ID.

Use the BrokerClient.toString method to obtain a string that contains names of the client, client group, and Broker for a Broker client.

Use the BrokerClient.isConnected method to determine whether a Broker client is currently connected to a Broker.

connect_state Meaning

CONNECT_STATE_DISCONNECTED The client has been disconnected.

CONNECT_STATE_CONNECTED The Client connection has been re-established, because automatic reconnect was enabled.

CONNECT_STATE_RECONNECTED The Client was disconnected, but the connection was re-established immediately. This only happens if the automatic reconnect feature is enabled and the connection is re-established before a disconnected state can be reported.



Use the BrokerClient.isClientPending method to determine whether there are any pending events for a particular Broker client.

Use the BrokerClusterPublisher.getClusterPublisherInfo method to determine whether there are any pending events for any Broker client in use by the application.

Client Queue Methods

Use the BrokerClient.getQueueLength method to determine the number of events currently waiting in a Broker client's event queue.

Use the BrokerClient.clearQueue method to empty the event queue associated with a Broker client.

Important! Use the BrokerClient.clearQueue method with care because it will delete events which have not yet been processed by the Broker client. If multiple clients are sharing the same client state, invoking this method can have far-reaching effects.

Advanced Features

The webMethods Broker Java API provides several advanced methods that you can use to manipulate network connections and to obtain platform information.

Connection Settings

Use the BrokerClient.getDefaultBrokerPort method to obtain the default IP port number that will be used by the BrokerClient constructor and the BrokerClient.reconnect method when connecting to a Broker.

The default port number is used for non-SSL connections and has a value of 6849. The default port number is also used to calculate the port numbers shown in the table below.

Port numbers calculated from the default port number

Client Time-out Settings

Use the BrokerClient.setDefaultClientTimeout method to set the default time-out for Broker requests. This method will also return the previous time-out settings.

Port number Description

default port number minus 1 Used for SSL connections without client authentication.

default port number minus 2 Used for SSL connections with client authentication.



The default connection time-out value is 30 seconds. You might find it useful to lower the connection time-out value in high-performance environments where a delay of 10 seconds probably indicates some sort of failure.

Platform Information

The platform information methods provide a way for your Broker clients to determine the version of the webMethods Broker Java API which they are using as well as the operating system and hardware platform on which they are executing.

Platform information is stored in the form of key-value pairs. The following keys are registered by the webMethods Broker Java API and cannot be changed. You can, however, add your own platform keys.

Use the BrokerClient.getPlatformInfo method to obtain the value associated with a particular key.

Use the BrokerClient.getPlatformInfoKeys method to obtain an array of all the currently defined platform keys.

Use the BrokerClient.setPlatformInfo method to set the value associated with a particular key. If the platform key you specify does not exist, it will be added along with its value.

Broker Territory and Broker-to-Broker Communication

webMethods Broker allows two or more Brokers to share information about their event type definitions and client groups. This enables communication between Broker clients connected to different Brokers. To share information, Brokers join a territory. All Brokers within the same territory have knowledge of one another's event type definitions and client groups. For more information on this feature, see Administering webMethods Broker.

Use the BrokerClient.getTerritoryName method to obtain the territory name of the Broker to which the Broker client is connected.

Broker Connection Descriptors

The attributes of the connection between a Broker client and a Broker are defined by the BrokerConnectionDescriptor object. You use the attributes in the connection descriptor to:

Key Value

AdapterLang "Java"

AdapterLangVersion <current API version>

OS The name of the operating system under which the caller is executing.

Hardware The name of the hardware platform on which the caller is executing.



Enable or disable the automatic re-connection of a Broker client in the case where the connection to the Broker is lost.

Enable or disable the sharing of a network connection by more than one Broker client. Only Broker clients located within the same process share a Broker connection.

Enable or disable the sharing of client state by multiple Broker clients.

Control the use of the secure socket layer (SSL) for authentication and encryption.

Enable or disable the redelivery counting feature and indicate whether the redelivery counter will operate in manual or automatic mode.

Enable or disable the keep-alive feature, which will prevent the client connection from being dropped without the Broker's knowledge.

Note: If you use a BrokerConnectionDescriptor to define the attributes of a connection, you must create the descriptor and set its attributes before you use it to create or reconnect a Broker client. Changing the attributes of a connection descriptor will not affect the Broker client currently using the descriptor, but it will affect any subsequent uses of the descriptor.

Creating Connection Descriptors

You can create a connection descriptor by calling a BrokerConnectionDescriptor constructors. By default, a newly created connection descriptor will have the following attributes:

Connection sharing is enabled.

Client state sharing is disabled.

Event ordering is set to AW_SHARED_ORDER_BY_PUBLISHER. See “By-Publisher Event Ordering” on page 55 for a description of event ordering.

The SSL certificate file is set to null.

The redelivery counting feature is disabled.

The keep-alive feature is disabled.

Obtaining a Client's Connection Descriptor

The BrokerClient.getConnectionDescriptor method allows you to obtain the connection descriptor for a particular Broker client.

Converting to String

Use the BrokerConnectionDescriptor.toString method to obtain a string containing the information associated with a connection descriptor.



Automatic Re-connection

You can use a connection description to enable automatic re-connection of a Broker client to a Broker in the event that the connection is lost. The automatic re-connection feature is disabled by default.

If your Broker client makes a request to the Broker and the connection has been lost, an attempt is made to reconnect to the Broker, just as if you had invoked the BrokerClient.newOrReconnect method.

You can use the BrokerConnectionDescriptor.setAutomaticReconnect method to enable or disable the automatic re-connection feature.

Use the BrokerConnectionDescriptor.getAutomaticReconnect method to determine whether this feature is currently enabled or disabled.

Using Automatic Re-connection

You can use automatic re-connection, along with the explicit-destroy life cycle and guaranteed storage options, to provide a high degree of reliability in your application design.

Broker clients that use the automatic re-connection feature can put their BrokerClient method invocations inside a retry loop and rely on the connection being established as needed. You might want to insert a time delay into these loops to avoid consuming too much CPU time.

Rules for Automatic Re-connection

Here are some important rules to keep in mind when using the automatic re-connection feature.

If the Broker disconnects from your client while the client is awaiting a reply from the Broker, a BrokerConnectionClosedException is reflected to the client and no re-connection is attempted.

If your Broker client is using the callback model for event processing, automatic re-connection will be attempted (when necessary) at any of these points:

Each time BrokerClient.dispatch is invoked.

Each time BrokerClient.mainLoop is invoked.

Each time an event is received by the BrokerClient.threadedCallbacks method on a client thread that is still connected.

Broker clients with an explicit-destroy life cycle that are automatically reconnected will find their previous client state has been preserved, including previously registered subscriptions, events in the event queue, and all other client state.



Note: For Broker clients with an explicit-destroy life cycle, previously retrieved events which were not acknowledged will be presented again after automatic re-connection. When a Broker client that is sharing its state with other clients is disconnected, the other clients retrieve the unacknowledged events. You can avoid receiving duplicate events by explicitly acknowledging events using the BrokerClient.acknowledge, BrokerClient.acknowledgeThrough, or BrokerClient.getEvent methods.

Broker clients with a destroy-on-disconnect life cycle that are automatically reconnected will find that any previously registered subscriptions, events in the event queue, and all other client state will no longer exist. These Broker clients use the connection notification feature to aid them in recreating their previous subscriptions and client state. For more information, see “Connection Notification” on page 46.

Using Client Keep-Alive

You can use the Broker client keep-alive feature for two purposes:

To quickly detect dropped client connections. This feature is useful in network configurations that might not notify the Broker until long after a client becomes disconnected (which, with some types of connections might be hours later).

To keep the client connection open through firewalls.

If client state is not shared, an undetected broken connection does not pose a problem. The Broker will automatically redeliver unacknowledged events to the client when it reconnects. However, when a client's state is shared, the Broker cannot distinguish the reconnection of a disconnected client from the ordinary reconnections of the other clients that are sharing the same state (shared clients all use the same client ID). As a result, the Broker will continue to hold that client's unacknowledged events in the queue until it receives an explicit disconnect notice from the network (generally, when the TCP/IP connection finally times out). If the shared-state client requires ordered events by publisher, the unacknowledged events will also prevent further processing of any additional events from their publishers.

You can avoid this condition by enabling the keep-alive feature in the connection descriptor. When enabled, the keep-alive feature causes the Broker to periodically check its connection to clients that are connected through the descriptor. To test the connection, the Broker sends a keep-alive message to any client that is idle for a specified period of time. If the client does not respond to the keep-alive message within a certain interval, the Broker explicitly disconnects it. By explicitly disconnecting the client, the client's unacknowledged events immediately become available for redelivery and can be retrieved by the other shared-state clients.

Setting the Keep-Alive Parameters

To specify the behavior of the Broker's keep-alive feature, use the BrokerConnectionDescriptor.setKeepAlive method. This method sets the following parameters in the BrokerConnectionDescriptor object:



KeepAlivePeriod. The number of seconds of idle time the Broker waits before issuing a keep-alive message to a client. To suppress keep-alive messages entirely, set KeepAlivePeriod to Integer.MAX_VALUE.

MaxResponseTime. The number of seconds the Broker waits for a response from the client after issuing a keep-alive message. This value must be greater than 0 and less that the Keep-Alive Period. Set the Max Keep-Alive Response Time to Integer.MAX_VALUE to specify an infinite response time.

RetryCount. The number of times the Broker resends a keep-alive message to a non-responsive client before disconnecting that client.

How you configure the keep-alive settings depends upon the reason for which you are using keep-alive.

For zombie session removal, you set a fairly short keep-alive interval, typically in seconds, so that you can quickly remove any zombie sessions.

For keeping the connection open through firewalls, you set a keep-alive interval closely matching the firewall time-out period, which is typically in minutes. This prevents the firewall from shutting down the connection because of inactivity.

The following code fragment uses the setKeepAlive method to specify a KeepAlivePeriod of 90 seconds, a MaxResponseTime of 30 seconds, and a RetryCount of 5.

BrokerConnectionDescriptor desc;

/* Create descriptor */ desc = new BrokerConnectionDescriptor(); desc.setKeepAlive(90,30,5);

Be aware that different combinations of the KeepAlivePeriod, MaxResponseTime, and RetryCount produce distinctly different behaviors. For details, see the parameter descriptions for the BrokerConnectionDescriptor.setKeepAlive method.

Important! Client keep-alive uses server resources. If you have a large number of clients, the Broker Server may become bogged down servicing these requests. In situations such as these, increasing the default keep-alive period may be necessary. Make sure to set the keep-alive values appropriately and do not over-use the feature.

Getting the Current Keep-Alive Parameters

Use the following methods to obtain the current values of the keep-alive settings:

BrokerConnectionDescriptor.getKeepAlivePeriod method.

BrokerConnectionDescriptor.getKeepAliveResponseTime method.

BrokerConnectionDescriptor.getKeepAliveRetryCount method.

The following example checks whether the values of KeepAlivePeriod and MaxResponseTime are set to Integer.MAX_VALUE. (When both KeepAlivePeriod and MaxResponseTime are set to Integer.MAX_VALUE, it disables the keep-alive feature entirely).



BrokerConnectionDescriptor desc; . . . boolean isDisabled; isDisabled = (desc.getKeepAlivePeriod() == Integer.MAX_VALUE) &&

(desc.getMaxResponseTime() == Integer.MAX_VALUE) ; . . .

Using the Keep-Alive Feature with a Shared Connection

If you want your clients to use the keep-alive feature and also share a connection, all clients sharing the connection must use the same BrokerConnectionDescriptor object or, if using individual BrokerClientDescription objects, must use identical keep-alive parameter values.

Sharing Connections

The webMethods Broker API improves client application performance by having all of your Broker clients that are accessing the same Broker share a single connection. If your client application has special requirements, you override this behavior.

Use the BrokerConnectionDescriptor.setConnectionShare method to enable or disable the sharing of a particular connection by more than one Broker client.

Use the BrokerConnectionDescriptor.getConnectionShare method to determine whether a particular connection be shared by more than one Broker client.

Sharing Client State

webMethods Broker allows Broker clients in different applications to share the same client state. Sharing client state allows several Broker clients, possibly executing on different hosts, to handle events in a parallel, first-come, first-served basis. This provides both parallel processing and load balancing for event handling.

One use for state sharing is load balancing event flows. If you have an application that processes request events (the webMethods Broker dbAdapter is one example), you might want to have several instances of the application available to process these requests.

Broker clients sharing the same client state are treated as one Broker client with regard to the state they are sharing. Any changes to the event subscriptions or event queue, such as clearing the queue, will affect all of the clients sharing the state.



Event Processing with Shared Client State

You have two options for how the Broker will present events to Broker clients that are sharing the same client state. The default event ordering is called by-publisher and is described on “By-Publisher Event Ordering” on page 55. You can also specify no ordering, as described on “Event Processing without Ordering” on page 56.

The BrokerConnectionDescriptor.getSharedEventOrdering method returns the current event processing order as either BrokerConnectionDescriptor.SHARED_ORDER_NONE or BrokerConnectionDescriptor.SHARED_ORDER_BY_PUBLISHER.

Use the BrokerConnectionDescriptor.setSharedEventOrdering method to specify the event processing order that you want.

By-Publisher Event Ordering

The Broker guarantees that events from a single publishing client cannot be processed out of order. This has important implications when several Broker clients are sharing the same event queue. The table below shows a client event queue containing events received from three different publishing clients; Broker client A, Broker client B, and Broker client C.

Consider these steps:

1 BrokerClient X receives the event from queue position 1 without acknowledging the event.

2 BrokerClient Y receives the event from queue position 2 without acknowledging the event.

3 When BrokerClient Y then asks for another event, it is given the event from queue position 4 because the last event published by Client A has not yet been acknowledged. For more information on acknowledging events, see “Using Sequence Numbers” on page 145.

Publishing Client Event Queue Position

BrokerClient A 1

BrokerClient B 2

BrokerClient A 3

BrokerClient C 4

BrokerClient B 5

BrokerClient C 6



Event Processing without Ordering

Invoke the BrokerConnectionDescriptor.getSharedEventOrdering method, specifying a value of SHARED_ORDER_NONE, to indicate that you do not want the Broker to guarantee the order of event processing. With an event ordering of SHARED_ORDER_NONE, events will be presented to any of the Broker clients sharing the client queue in the order in which they appear in the queue.

When is Sharing State Useful?

A shared-state client is useful only if it receives events that it can process in parallel. For example, a shared-state client makes sense if it will receive events from one or more publishers and it can process those events in any order (i.e., SHARED_ORDER_NONE). It also makes sense in cases where events must be processed in order by publisher (i.e., SHARED_ORDER_BY_PUBLISHER), and the events come from multiple publishers.

A share-state client is not useful in a situation where it receives events from only a single publisher and those events must be processed in order (i.e., SHARED_ORDER_BY_PUBLISHER). Under these circumstances, the shared-state client would be required to process all events serially. It would provide no performance benefits, because, in this case, the shared-state client would never receive any events that it could process in parallel.

State Sharing Methods

Use the BrokerConnectionDescriptor.getStateShare method to determine whether client state sharing is enabled or disabled for a particular connection descriptor.

Use the BrokerConnectionDescriptor.setStateShare method to enable or disable the sharing of the client state associated with the connection descriptor.

In addition to these methods, you can use the BrokerClient.getConnectionShareLimit and BrokerClient.setConnectionShareLimit methods to obtain and limit the number of Broker clients that can share a particular client state.

Calling Sequence for Sharing Client State

You can follow the steps below to allow multiple Broker clients to share the same client state.

1 Create a new BrokerConnectionDescriptor and set the state sharing to true.

2 Create a new BrokerClient, passing a client ID and the descriptor created in step 1.

3 After the Broker client is created with shared state, other Broker clients using the same Broker can use the BrokerClient.reconnect method, along with the client ID from step 2, to connect to the Broker client. No special BrokerConnectionDescriptor settings are required when reconnecting.

Note: All Broker clients that are to share the same state must be connected to the same Broker.



Priority Ordering for Broker Queues

The BrokerEvent.getPriority method and BrokerEvent.setPriority method allows you to order the documents in a queue by priority. To use priority ordering:

A publisher assigns the priority to the messages that it publishes and

The client enables the priority queue.

Note: After you create a client with priority queue enabled, it is always priority enabled. You cannot turn the priority enabling off.

For Broker, implementation of priority messaging is based on server-side implementation of the priority queue. Each document is queued for delivery to the subscriber in the following order: (1) priority and (2) publication time. Documents are ordered by priority at the destination queue when the document is inserted into the destination client's queue, if that queue has priority ordering enabled. Priority ordering does not apply to forward queues, when documents are forwarded to subscriptions in territories, so there is a possibility that lower priority documents are delivered before incoming higher priority documents are delivered to the queue.

For priority values, Broker uses the same values according to JMS specifications: priority values are from 0-9, where 0 is the lowest priority and 9 is the highest priority (expedited processing). The default value is 4.

Broker maintains the priorities through a set of priority cursors. These priority cursors are not persisted to disk, so the cursors are lost when you restart Broker. As a result, when you shut down Broker and restart it:

All the priority cursors are reset to empty.

All the existing documents in the queue are delivered with the default priority of 4.

Any arriving documents are prioritized and delivered in priority order.

This means that after restarting the Broker, the priority of any new document places that document relative to the priority of the old documents, which now all have a default value of 4. For example, if you have a document A with a priority of 9 and you have to restart the Broker, document A and all of the documents still in the queue are now assigned the default priority of 4. When the queue receives any new documents after restarting the Broker, priority ordering applies to those new documents. So, if after restart, the new document B has a priority of 7, document B will now have a higher priority than document A, even though document A initially had a higher priority of 9.

Priority Ordering and Performance

All client queues have a retrieval cursor. This cursor speeds up access to messages when there are a large number of unacknowleged messages in the queue that are not candidates for retrieval.



In situations where there are a large number of unacknowledged messages in the queue (such as might happen with JMS clients that control client acknowledgment), it is possible for messages to be inserted into the client queue ahead of the retrieval cursor, regardless of their priority.

To remedy this situation, Broker resets the retrieval cursor back to the beginning of the client queue to re-evaluate all messages in the queue after an insert operation is made. If the number of messages in the queue is small, the impact of the reset operation on performance is negligible; however, if the number of messages is large, there could be noticeable effect on performance. Therefore, if your client queues maintain a large number of unacknowledged messages, consider turning priority messaging off if you notice an unacceptable impact on performance.

Using Security Features

For more information on enabling basic authentication, see“Working with Basic Authentication” on page 193.

For more information on enabling SSL features, see “Working with SSL” on page 197.

Redelivery Counting

The BrokerConnectionDescriptor.setAutomaticRedeliveryCount method and the BrokerConnectionDescriptor.setRedeliveryCountEnabled method enables the redelivery counting feature for a BrokerClient. When redelivery counting behavior is enabled, the Broker maintains a counter for each guaranteed event that it sends to the BrokerClient. By testing the value in the counter, your client can determine whether it has received an instance of a particular event before.

The redelivery feature can be used in manual or automatic mode. The mode you select determines whether the redelivery counter is incremented by the Broker or by your client. When you use automatic mode, the Broker updates the redelivery counter prior to sending a event to the client. When you enable manual mode, your client must explicitly increment the redelivery counter when it receives an event.

To check whether redelivery counting is enabled, you use the BrokerConnectionDescriptor.getAutomaticRedeliveryCount method and the BrokerConnectionDescriptor.getRedeliveryCountEnabled method.

Note: A redelivery counter is maintained for guaranteed events only. Volatile events always has a redelivery count of -1. Additionally, if a client does not enable redelivery counting, all events that it receives will have a redelivery count of -1.

For more information about using the redelivery counting feature, see “Detecting Redelivered Events” on page 95.


3 Using the Callback Model

Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60

Understanding Callbacks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60

General Callback Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62

Specific Callback Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63

Dispatching Callback Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64



Overview

This chapter describes the webMethods Broker Java API for receiving and processing events using the callback model. Reading this chapter will help you to understand:

How to register general and specific callback objects.

How to derive your own callback object from the BrokerCallback interface.

How to retrieve and process events from the Broker using callback objects.

Understanding Callbacks

The callback model for processing event types allows your client application to register one or more callback objects to process event types for a Broker client. Unlike the get-events model, which can only process event types for one Broker client at a time, the callback model can receive any event type for any of your client application's Broker clients and then dispatch it to the appropriate callback object's event handling method. If your client application creates several Broker clients, using the callback model frees your application from making separate calls to one of the webMethods Broker get-event methods for each Broker client.

Using Callbacks

Follow these steps to use the callback processing model:

1 Declare your callback objects

2 Verify that the subscription(s) that you want is (are) allowed using BrokerClient.canSubscribe.

3 Register the subscription(s) using one of the BrokerClient.newSubscription methods.

4 Register a general callback object using BrokerClient.registerCallback.

5 Next, you can optionally register any specific callback objects you want, using:

BrokerClient.registerCallbackForSubId

BrokerClient.registerCallbackForTag

6 Process events using one of the following methods:

BrokerClient.dispatch

BrokerClient.mainLoop

BrokerClient.threadedCallbacks

7 Cancel all the callbacks using BrokerClient.cancelCallbacks, cancelCallbackForSubId, or cancelCallbackForTag.

8 Cancel all the subscriptions using one of the BrokerClient.cancelSubscription methods.



Implementing a Callback

All callback objects that you register must be derived from the BrokerCallback interface. When deriving your own class from BrokerCallback, you must provide an implementation for the handleBrokerEvent method. This method has the following declaration:

public boolean handleBrokerEvent( BrokerClient client, BrokerEvent event, Object client_data);

Your method should return true if its processing was successful or false if a failure occurred. If true is returned, the event will be acknowledged automatically. For information on acknowledging events, see “Using Sequence Numbers” on page 145.

Note: If you want to save a copy of an event passed to a callback method, you must use the BrokerEvent copy constructor.

Passing Arguments to Callback Methods

When you register your callback object, you can specify a client_data object that might be necessary for the callback method to complete its processing. The client_data parameter might refer to state information that the callback method must access and update each time it is invoked.

Assume that you want to count the number of events that your application processes. When you register your callback object, you could use the client_data value to refer to the counter variable. When the callback object's event handling method is invoked, it can increment the counter.

The following example illustrates how to set up an argument for a callback object:

class IntHolder { int count;

}; static IntHolder counter; . . . public static void main(String args[]) {

int n; counter.count = 0; SampleCallback sample_callback = new SampleCallback(); . . . /* Check if can subscribe */ . . . /* Register callback */ try {

client The client for which the event has been received.

event The event that is being dispatched to this method.

client_data Any data that you want to be passed to this method when it is invoked.



c.registerCallback(sample_callback, counter); } catch (BrokerException ex) {

System.out.println("Error on registering callback\n"+ex); return; } . . .

The following example illustrates the SampleCallback.java implementation:

public boolean handleBrokerEvent(BrokerClient c, BrokerEvent e, Object counter)

{ /* increment counter */ counter.count++; /* perform rest of event processing */ . . .

}

General Callback Objects

When using the callback model, you must register a general callback object for each Broker client by calling the BrokerClient.registerCallback method. When an event is received, if there are no specific callback objects registered which match the event's subscription identifier or tag, the general callback object's handleBrokerEvent method will be invoked to handle the event.

You can have a single callback object process all of your application's events by making a separate BrokerClient.registerCallback call for each BrokerClient that your application uses, specifying the same callback object each time.

Depending on the complexity of your design, you might find that a single, general callback object is all that your client application requires.

Note: You must register a general callback object before registering any specific callback object.

Using General Callbacks

The following example contains an excerpt from the subscribe3.java that shows the use of the BrokerClient.registerCallback method to register a general callback object.

class subscribe3 {

. . . static int num_to_receive = 10; public static void main(String args[]) {

. . . SampleCallback2 sample_callback =

new SampleCallback2(num_to_receive); /* Create a client */ . . .



/* Check if can subscribe */ . . . /* Register callback */ try {

c.registerCallback(sample_callback,null); } catch (BrokerException ex) {

System.out.println("Error on registering callback\n"+ex); return;

} /* Open the subscription */

. . . /* Do main loop */ try {

BrokerClient.mainLoop(); } catch (BrokerException ex) {

System.out.println("Error on dispatch\n"+ex); return;

} . . .

Specific Callback Objects

Depending on the complexity of your design, you might find that a single, general callback object is all that your client application requires. More complicated designs might need to make use of specific callback objects.

A specific callback object is only used to process an event with a particular subscription identifier or event tag for a particular Broker client. You can register a specific callback object by calling either the BrokerClient.registerCallbackForSubId method, or BrokerClient.registerCallbackForTag method.

Event tag fields are part of the request-reply model, described in “Using Request-Reply” on page 107.

Note: If a received event matches the criteria for more than one callback, each callback objects handleBrokerEvent method will be invoked to handle the event.

Using Specific Callbacks

The following example illustrates how to register a specific callback object using the use of the BrokerClient.registerCallbackForSubId method.

. . . public static void main(String args[])

{ . . . SampleCallback1 general_callback =

new SampleCallback1(num_to_receive); SampleCallback2 specific_callback =

new SampleCallback2(num_to_receive); /* Create a client */ . . .



/* Check if can subscribe */ . . . /* Register general callback */ try {

c.registerCallback(general_callback,null); } catch (BrokerException ex) {

System.out.println("Error on registering general callback\n"+ex); return;

} /* Register specific callback with a subscription ID of 1 */

try { c.registerCallbackForSubId(1, specific_callback,null);

} catch (BrokerException ex) { System.out.println("Error on registering specific callback\n"+ex); return;

} /* Open the subscription with a subscription ID of 1 */ try {

c.newSubscription( 1, "Sample::SimpleEvent",null); } catch (BrokerException ex) {

System.out.println("Error on create subscription #1\n"+ex); return;

} /* Do main loop */ try {

BrokerClient.mainLoop(); } catch (BrokerException ex) {


} . . .

Dispatching Callback Methods

After registering your subscriptions callback object, your client application should then call one of the webMethods Broker dispatching methods to receive events and dispatch the appropriate callback object's event handling method. Only one of the following dispatching methods should be used.

Using dispatch

The BrokerClient.dispatch method can be used to wait to receive a single event for any Broker client, dispatch the event to the appropriate callback object's event handling method, and then return. The subscribe2.java sample application provides an examples of how to use BrokerClient.dispatch.



Using mainLoop

The BrokerClient.mainLoop method is similar to BrokerClient.dispatch, except that it enters an event loop that will continue to receive and dispatch events until BrokerClient.stopMainLoop is called. The subscribe3.java sample application provides an example of how to use BrokerClient.mainLoop.

Using threadedCallbacks

The BrokerClient.threadedCallbacks method will create a thread that invokes BrokerClient.mainLoop. Using this method can simplify your application code because it handles the thread creation for you. The subscribe4.java sample application provides an example of how to use BrokerClient.mainLoop.

Invoking threadedCallbacks(true) is identical to creating a thread and invoking the BrokerClient.mainLoop method on that thread.

Invoking threadedCallbacks(false) is identical to invoking the BrokerClient.stopMainLoop method.

Event Dispatching Rules

When an event is received in the callback model, the following rules are used to dispatch the event.

1 If the received event has a tag field and the tag matches a registered callback, the received event is dispatched to that callback object's event handling method.

2 If the received event has a subscription identifier, the event is dispatched once to each callback object that matches the subscription identifier. If the event matches two event subscriptions with the same subscription identifier, the event will be dispatched twice to the callback object for that identifier.

3 The received event will be dispatched to the general callback object's event handling method if the tag did not match any callback and:

a At least one subscription identifier did not match a specific callback.

b No subscription identifiers were matched because the event was delivered.




4 Creating and Initializing Events

Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68

Event Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68

Creating Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70

Event Data Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72

Regular Data Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73

Sequence Data Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75

Structure Data Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78

Envelope Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80

Specifying Field Names . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86



Overview

This chapter describes the webMethods Broker objects and methods for creating BrokerEvents and setting their field values. Reading this chapter will help you understand:

Event types and event names.

Event fields, including regular fields, sequence fields and structure fields.

How to create a BrokerEvent object.

How to set event field values.

How to obtain the value from an event field.

Event envelope fields.

How to set and obtain envelope fields.

How to quickly populate a BrokerEvent object's fields from a storage object you define.

How to quickly populate a storage object you define with the field values from a BrokerEvent object.

How to improve performance by creating BrokerEvent objects that use storage classes.

Event Overview

The first step in implementing your application is to define the content of the events that will be used to communicate information between your client applications and the Broker. Events are defined using Software AG Designer, described in the Software AG Designer Online Help.


Events contain data that allow applications to communicate with each other. An event can be used to represent:

Requests to a database application to retrieve or write data.

Banking transactions such as deposits, withdrawals, and transfers.

News headlines, stock quotes, or money exchange rates.

Customer orders, invoices, packing slips, or credit memos.

Event Types

An event type defines the event's name as well as the fields that it contains. webMethods Broker API objects, like BrokerEvent, use event type definitions to verify that an event's fields are set with values that match their defined types. Event type definitions are also used if you call the BrokerEvent.validate method to validate an event's fields.



Note: Events created without a BrokerClient context are not type checked. See “Field Type Checking” on page 71 for more information.

Event Type Cache

The webMethods Broker API copies the event type definitions used by your application from the Broker to which you are connected into a local event type cache. The cache improves the performance of the event field type checking process and its use is usually transparent to you. For more detailed information, see “Managing Event Types” on page 151.

Event Type Names

Each event type has a unique name that distinguishes it from other event types.

Note: “Parameter Naming Rules” on page 419 describes the restrictions on event type names.

Event types are organized into event families, allowing you to group all of the events related to a particular application domain. An event type name consists of two components; a scope and a base name.

Scope::BaseName

The scope component can consist of one or more levels. Consider the following fully qualified event type name.

WesternRegion::Hardware::Sales::receiveCustOrder

The base name for this event type would be receiveCustOrder.

The scope would be WesternRegion::Hardware::Sales.

Use the BrokerEvent.getTypeName method to obtain the fully-qualified name for an event type.

Use the BrokerEvent.getBaseTypeName method to obtain the name for an event type event type without the scope qualification.

Use the BrokerClient.getEventTypeNames method to obtain the fully-qualified names of all the event types known to the Broker to which your Broker client is connected.

Use the BrokerClient.getScopeNames method to obtain the fully-qualified names of all the event types known to the Broker to which your Broker client is connected. All event scopes that contain at least one event type will be returned.

Note: Only the names of the event types which your client is permitted to browse are returned by the getEventTypeNames and getScopeNames methods. In most cases, this corresponds to the set of event types which your client can publish or for which it can register subscriptions.



Use the BrokerEvent.getScopeTypeName method to obtain the scope name from a particular event.

Event Fields

Every event contains envelope fields and data fields. Envelope fields are consistent for all event types and contain details about the event's sender, destination, and its transit. Envelope fields are described on “Envelope Fields” on page 80.

Event data fields contain the data that your client applications use to exchange information. Event data fields can contain a single value, a sequence of values with the same type, or a structure containing values of different types, or a pre-defined Event Type. Event data fields are discussed on “Event Data Fields” on page 72.

Note: “Parameter Naming Rules” on page 419 describes the restrictions on event field names.

Event Identifier

When an event is published, described in “Publishing and Delivering Events” on page 131, the Broker will assign the event an event identifier that you can use to determine whether two events are exactly the same. You can also use the event identifier to match events with trace events or activity traces, described in the webMethods Broker Administration Java API Programmer’s Guide. An event identifier is almost certainly unique. It is possible, though extremely unlikely, for two Brokers to generate the same event identifier.

You can retrieve the event identifier using the BrokerEvent.getEventId method.

Creating Events

Before your client application can publish or deliver an event, it must create the event and set the event's fields. The example below contains an excerpt from the publish1.java sample application that shows the creation of a new event. The constructor takes the following parameters:

A BrokerClient reference.

The name of the event type. In the following example, the event scope is "Sample" and the event type name is "SimpleEvent":

. . . public static void main(String args[]) { BrokerClient c; BrokerEvent e; /* Create a client */ . . .



/* Create the event */ try {

e = new BrokerEvent(c, "Sample::SimpleEvent"); } catch (BrokerException ex) {

System.out.println("Error on create event\n"+ex); return;

} . . .

General Event Methods

After creating an event, you can use the BrokerEvent copy constructor to create a new event, copying the contents of an existing event to the new event.

Use the BrokerEvent.hasBeenModified method to determine whether the contents of an event have been modified.

Use the BrokerEvent.clearModificationFlag method to mark an event as having not been modified.

Use the BrokerEvent.setModificationFlag method to mark an event as having been modified.

Use the BrokerEvent.toString method to format an event's fields into a string.

Use the BrokerEvent.toFormattedString method to format selected event fields into a string. One version of this method allows you to specify the Locale you want to be used in formatting the string.

Use the BrokerEvent.toLocalizedFormattedString method to format selected event fields into a string using the Locale that you specify.

Use the BrokerEvent.toLocalizedString method to format selected event fields into a string using the current Locale.

Use the BrokerEvent.getClient method to obtain the Broker client associated with an event.

Field Type Checking

When you create an event with a BrokerClient reference, the following field type checking rules will be applied to the event.

1 All event fields will appear to be set on the event at the time the event is created.

2 You are not allowed to set a field which does not exist for the event type.

3 You cannot set an event field with a data type other than that defined by the event type.

When you create an event with a nullBrokerClient reference, the following type checking rules will be applied to the event.

1 You can set fields with any field name and any data type.

2 Any attempt to retrieve an event field that was not previously set will cause a BrokerFieldNotFoundException exception to be thrown.



3 After a field has been set, you are not allowed to change the field's type without first clearing the event field, using the BrokerEvent.clearField method or clearing the entire event using the BrokerEvent.clear method.

Note: For most applications, you should create an event within the context of a Broker client so that type checking will occur.

Converting Events as Binary Data

Use the BrokerEvent.toBinData method to obtain a binary array representation of a BrokerEvent that is suitable for saving to disk.

Restoring Events from Binary Data

Use the BrokerEvent.fromBinData method to initialize a BrokerEvent from a binary array that was generated from an earlier call to BrokerEvent.toBinData. When re-creating the event, you can specify an associated BrokerClient if you want the event's contents to be type checked.

Event Data Fields

Data fields contain application-specific data that your application will set before publishing an event or will retrieve when processing a received event. Each field has a name and a specifically typed value. Event data field values are stored in a platform-independent representation that allows client applications executing on different hardware platforms and under different operating systems to easily exchange data without worrying about bit significance or byte ordering. The conversion from webMethods Broker's platform-independent data representation to the local data representation is handled transparently by the BrokerEvent get and set methods.

Field Data Types

The following table shows the data types used by client applications for regular, sequence struct, and event data fields.

Event Type Editor Type Java Language Type Description

boolean boolean 1 (true) or 0 (false), stored as a single byte.

byte byte Signed 8-bit integer.

char char A single character.

date BrokerDate An object representing the year, month, day, hour, minute, second, and millisecond.



Use the BrokerTypeDef.getFieldType method to obtain an event field's type.

Obtaining Field Names

You can use the BrokerEvent.getFieldNames method to obtain the names of all the fields contained in a particular event.

Regular Data Fields

A regular data field in an event contains a single value that is obtained and set using the field name and an appropriately typed source or target value.

Setting Regular Data Fields

Several methods are provided for setting a regular data field, based on it's type. These methods are described in BrokerEvent.set<type>Field. The source value for the field being set depends on the field's type, as shown in the table below.

double double Double-precision floating point number.

event A separate, previously defined, event type.

float float Standard-precision floating point number.

int int Signed 32-bit integer.

long long Signed 64-bit integer.

sequence Sequence of any regular data types (such as, boolean, byte, char, date, etc.)

short short Signed 16-bit integer.

string String A string of characters.

struct A set of basic Java types

unicode char char Used for unicode, char (double byte)

unicode string String Used for unicode, double byte

unknown If the application is unable to identify a field, then it is categorized at "unknown."

BrokerEvent Method Value Type

setBooleanField boolean

Event Type Editor Type Java Language Type Description



The following example contains an excerpt from the publish1.java sample application that shows the use of the BrokerEvent.setIntegerField method. This method takes the following parameters:

The name of the event field to be set.

The value for the field.

BrokerEvent e; int count; . . . count = 1; /* Publish */ while (count < num_to_publish) {

try { e.setIntegerField("count",count);

} catch (BrokerException ex) { System.out.println("Error on setting event field\n"+ex); return;

} . . .

If you attempt to set a field with a value that does not match its defined type, an exception might be thrown. Type checking will not occur if the event whose field is being set was created without a Broker client context, as described in “Field Type Checking” on page 71.

You can also use the BrokerEvent.setField method to set an event field.

Getting Regular Field Values

Several methods are provided for obtaining the value of a regular event data field, based on its type. These methods are described in BrokerEvent.get<type>Field. The type of the value being retrieved depends on the field's type, as shown in the table below.

setByteField byte

setCharField char

setDateField BrokerDate

setDoubleField double

setFloatField float

setIntegerField int

setLongField long

setShortField short

setStringField String




The following example contains an excerpt from the subscribe1.java sample application that shows the use of the BrokerEvent.getIntegerField method. This method requires the name of the event field you want to retrieve.

BrokerEvent e; int pub_count; . . .

try { pub_count = e.getIntegerField("count");

} catch (BrokerException ex) { System.out.println("Error on getting count field\n"+ex); return;

} . . .

If you attempt to get a field value with a type that does not match the field's defined type, an exception might be thrown. Type checking will not occur if the event whose field is being obtained was created without a Broker client, as described in “Field Type Checking” on page 71.

You can also use the BrokerEvent.getField method to obtain the value and type of an event field.

Sequence Data Fields

Sequence data fields contain a sequence of several values with the same data type. A sequence field can contain any of the types mentioned for simple data fields. A multiple dimension array of values can be represented as a sequence within a sequence.


getBooleanField boolean

getByteField byte

getCharField char

getDateField BrokerDate

getDoubleField double

getFloatField float

getIntegerField int

getLongField long

getShortField short

getStringField String



Setting Sequence Fields

Several methods are provided for setting the values of the entire sequence, or a subset of the sequence. These methods are described in BrokerEvent.set<type>SeqField.

You can also use the BrokerEvent.set<type>Field to set a single value within a sequence field by specifying the field name with an index.

The following example shows the use of the BrokerEvent.setIntegerSeqField method. This method takes the following parameters:

The name of the event sequence field to be set.

The number of elements to skip from the beginning of the source array parameter.

The number of elements to skip from the beginning of the target sequence in the event.

The number of elements to be set.

The source array of values of the appropriate type.

Setting the values of an event sequence field

int count[5] = { 0, 1, 2, 3, 4}; . . . try { e.setIntegerSeqField("count", 0, 0, 5, count); } catch (BrokerException ex) { System.out.println("Error on setting sequence field\n"+ex); return; } . . .

The manner in which the source array is specified depends on the array's type.

BrokerEvent Method Name Sequence Value Type

setBooleanSeqField boolean[]

setByteSeqField byte[]

setCharSeqField char[]

setDateSeqField BrokerDate[]

setDoubleSeqField double []

setFloatSeqField float[]

setIntegerSeqField int[]

setLongSeqField long[]

setShortSeqField short[]

setStringSeqField String[]



Each of the BrokerEvent.set<type>SeqField methods can overwrite all or part of the destination sequence field. After the code shown in the example in “Setting Sequence Fields” on page 76 is executed, the sequence will contain:

[0 1 2 3 4]

If you then set three elements (3, 2, 1) into this same sequence at location 1, the sequence would then appear as:

[0 3 2 1 4]

An error will be returned if you attempt to set a field with a value that does not match its defined type.

These methods can also cause the destination sequence to grow in size, if a larger number of elements are stored into the sequence.

These methods never reduce the number of elements in the destination sequence. Use the BrokerEvent.setSequenceFieldSize method to reduce the size of a sequence field.

You can also use the BrokerEvent.setSequenceField method to set a sequence field.

Getting Sequence Field Values

Several methods are provided for obtaining all of the values from a sequence event field, or a subset of the sequence, with a single method call. These methods are described in BrokerEvent.get<type>SeqField.

You can also use the BrokerEvent.get<type>Field to obtain a single value from a sequence field by specifying the field name with an index.

The following example shows the use of the BrokerEvent.getIntegerSeqField method. This method takes the following parameters:

The name of the event sequence field being accessed.

The number of elements to skip from the beginning of the sequence field in the event.

The number of source elements to be retrieved.

int count_array[]; int num_retrieved; . . .

try { count_array = e.getIntegerSeqField("count", 0, 5);

} catch (BrokerException ex) { System.out.println("Error on getting sequence field\n"+ex); return;

} . . .

The manner in which the target array is specified depends on the sequence's type.

BrokerEvent Method Name Field Value Type

getBooleanSeqField boolean[]



You can also use the BrokerEvent.getSequenceField method to obtain the contents of a sequence field. The BrokerEvent.getSequenceFieldSize method can be used to obtain the number of elements contained in a sequence field.

Structure Data Fields

Structure data fields represent event fields with a user-defined type. A structure data field can contain members that are simple data types, arrays, or other structures.

Sample:StructEvent { string count; struct sample_struct {

BrokerDate sample_date; int sample_array [] [];

} }

Setting Structure Fields

Two methods, BrokerEvent.setStructFieldFromEvent and BrokerEvent.setStructSeqFieldFromEvents, are provided for setting all of the values within a structure field. The first method sets the entire contents of a single structure field and the second method sets the entire contents of a sequence of structure fields.

You can also use the BrokerEvent.set<type>Field to set the value of a single field within a structure field by specifying the appropriate field name.

Setting a Struct Field from an Event

Because structure fields can contain other fields, the BrokerEvent.setStructFieldFromEvent method allows you to set all of those contained values with just one method call. To use this method, follow these steps.

getByteSeqField byte[]

getCharSeqField char[]

getDateSeqField BrokerDate[]

getDoubleSeqField double[]

getFloatSeqField float[]

getIntegerSeqField int[]

getLongSeqField long[]

getShortSeqField short[]

getStringSeqField String[]

BrokerEvent Method Name Field Value Type



1 Create an empty event of any event type, using the BrokerEvent constructor. Because the data you will put into this event is not likely to match a real event type definition, create this event without a Broker client so it will not be type checked.

2 Set the fields and values of the event created in step 1 so that they match the fields in the structure you want to set. Use the BrokerEvent.set<type>Field and BrokerEvent.set<type>SeqField methods.

3 Call the BrokerEvent.setStructFieldFromEvent method, passing the event created in the above steps as the source value.

4 Envelope fields on the source event are ignored.

Setting a Struct Sequence Field from an Event

Similar in concept to BrokerEvent.setStructFieldFromEvent, the BrokerEvent.setStructSeqFieldFromEvents method sets a sequence of structure fields from an array of events. Envelope fields on the source events are ignored.

As with the other methods for setting sequence fields, this method might overwrite all or part of the destination structure sequence field. It might also increase the size of the target sequence, but it will never reduce the size of the sequence. To reduce the size of a sequence field, use the BrokerEvent.setSequenceFieldSize method.

Getting Structure Field Values

Two methods, BrokerEvent.getStructFieldAsEvent and BrokerEvent.getStructSeqFieldAsEvents, are provided for obtaining some or all of the values from a structure field in a single method call. The first method obtains all of the values of a single structure field and the second method obtains all the values from a sequence of structure fields.

You can also use the BrokerEvent.get<type>Field to obtain the value of a single field within a structure field by specifying the appropriate field name.

Getting a Struct Field as an Event

Because structure fields can contain other fields, the BrokerEvent.getStructFieldAsEvent method allows you to obtain all of those contained values with just one method call.

As described on “Field Type Checking” on page 71, the retrieved event that represents the structure is not type checked.

Getting a Struct Sequence Field

Similar in concept to BrokerEvent.getStructFieldAsEvent, the BrokerEvent.getStructSeqFieldAsEvents method obtains a sequence of structure fields as an array of events. Envelope fields on the target events are ignored.

As described on “Field Type Checking” on page 71, the retrieved events that represent the structures are not type checked.



Envelope Fields

Many of the event envelope fields are managed for you by the webMethods Broker API methods. Some event fields can be set by your application and others contain values set by the Broker. You cannot set the envelope fields that are set by the Broker, but you can retrieve their values.

Note: Unlike other event fields, attempting to retrieve an envelope field that has not been set will cause a BrokerFieldNotFoundException to be thrown.

Envelope Field Event Editor Type Description

activation unicode_string A unique identifier set by the event's publisher to identify a one-time execution of an integration solution.

appSeqn int Sequence number, set by the event's publisher. Your application defines how this field is used. The conventional way to use this field is to count upward from 1.

appLastSeqn int Sequence number, set by the event's publisher. Your application defines how this field is used. Generally used to identify the last event in a sequence of events.

appPassword unicode_string Password of user in appUserName. Used if the resource that processes the event requires authentication.

appUsername unicode_string Represents a user's name.

businessContext unicode_string Used internally to track business process context and audit context.

controlLabel short[] Represents the access label that a receiving client must have to receive the event.

errorsTo unicode_string The client ID to which the event should be forwarded if any errors are generated when this event should be sent, instead of sending to the originator of the request.

errorRequestsTo unicode_string The client ID to which a request event will be forwarded if any errors generated processing the request. If field is not set, any request event that generates an error will be discarded.



eventTraceInfo unicode_string Used internally to append the trace information to documents. This trace information provides insight about the flow of document through the different systems. Used by webMethods Insight. This field can be used by your application if webMethods Insight is not tracing the document flow.

locale unicode_string Locale of the publishing client expressed as a URN (Uniform Resource Name).

maxResults int The maximum number of reply events a requestor would like to receive. A value of 0 indicates that no reply or acknowledgment should be sent for this event.

priority int Message priority of values from 0-9, where 0 is the lowest priority and 9 is the highest priority (expedited processing). The default is 4.

replyTo unicode_string The client ID to which the replies to this event should be sent, instead of sending to the originator of the request.

signature byte[] A byte sequence that holds a digital signature.

signatureType unicode_string Describes the type of digital signature being used.

startResult int A value >= 0 that specifies the starting number of the event to receive. Often used in conjunction with maxResults.

tag int Used in the request-reply model, described in “Using Request-Reply” on page 107, to match a request event with its corresponding reply event.

trackId unicode_string This field's value can be set by a publishing client application to a unique identifier for tracking purposes. This allows an event that is re-published to be tracked. It also allows multiple events associated with a single logical transaction to be tracked. If not set, this field should be treated as if it contained the same value as the pubId field.




The appSeqn and appLastSeqn can be used by your publisher and subscriber applications for whatever purpose they require. One possibility is to track a sequence of events which represent a response to a single request event. Your publisher could start appSeqn at 1 and set appLastSeqn to the sequence number of the last event in the sequence. If your publisher does not know the length of the sequence when it starts publishing, then appLastSeqn need not be set. When your publisher is about to publish the last event of the sequence, appLastSeqn could be set to equal appSeqn. Setting both appSeqn and appLastSeqn to -1 indicates the event is empty.

If you want your publisher to have a continuous stream of sequence numbers, then you should use BrokerEvent.setPublishSequenceNumber method to set the appropriate number prior to publishing the event.

Note: The BrokerEvent.setPublishSequenceNumber method does not actually set the pubSeqn envelope field. Instead, it specifies the sequence number that the Broker is to use when the event is published by your Broker client.

Read-only Envelope Fields

The table below shows the envelope fields used by the Broker which your application can retrieve, but not alter.

Note: Attempting to retrieve an envelope field that has not been set will cause a BrokerFieldNotFoundException to be thrown.

transactionId unicode_string This field's value can be set by a publishing client application to indicate that an event is part of a transaction. See “Transaction Semantics” on page 121 for more information.

transformState unicode_string This field allows clients that transform data to mark an event's current state. An event could be published with a transformState value of "USEnglish". A receiving client could translate the event into French and publish it with a transformState value of "French".





age int The cumulative time, in seconds, that the event spends on all Brokers.

The Broker starts tracking the age of an event when it receives the event from the publishing client.

The Broker stops tracking the age of an event when the subscribing client removes the event from the client queue.

If the event is routed to successive Brokers, age also includes the length of time the event spends on the other Brokers.

connectionIntegrity

unicode_string Indicates whether or not the received event passed over an insecure link.

destId unicode_string Client ID of the event's recipient. This is used only with delivered events, described on “Delivering Events” on page 133.

enqueueTime date The date and time that the Broker enqueued the event for the recipient.

logBroker unicode_string The name of the Broker that has this event in its log.

logHost unicode_string The host name and port number of the Broker that has this event in its log.

pubDistinguishedName

unicode_string The distinguished name of the Broker client that published the event using an SSL connection.

pubId unicode_string Client ID of the event's publisher. If the publishing client is connect to a different Broker than the recipient, the ID will be fully qualified (prefixed with the name of the publisher's Broker).

pubNetAddr sequence of bytes A sequence of six bytes containing the IP address and port number of the event's publisher. See “The pubNetAddr Envelope Field” on page 85 for more information on this field.



Your application can use the BrokerEvent.get<type>Field methods to obtain the values of an event that it has received. Be sure to use the appropriate method for the envelope field's type.

Note: When referring to envelope fields, you must add _env. to each of the field names shown in the table above.

The example below shows how your Broker client can retrieve the pubSeqn value of a received event by using the BrokerEvent.getLongField method and specifying the _env.pubSeqn field name.

. . . BrokerEvent e; long seqNumber;

. . . try {

seqNumber = e.getLongField("_env.pubSeqn"); } catch (BrokerException ex) {

System.out.println("Error on getting envelope field\n"+ex); return;

} . . .

The connectionIntegrity Envelope Field

The connectionIntegrity envelope field is a read-only field that describes the integrity of the Broker-to-Broker connections that were used to transport the event.

pubSeqn long A 64-bit value representing the event's publish sequence number. The use of publish sequence numbers is described in “Using Sequence Numbers” on page 145.

pubLabel short[] Set by the Broker for an event publish by a client which has an access label.

recvTime date The date and time the event was received by the Broker.

route sequence of structs

See “The route Envelope Field” on page 85 for more information on this field.

uuid unicode_string Universally unique identifier assigned to the event. Used to detect duplicate events.

Value Meaning

empty string At some point, the event traveled over a connection that was not encrypted.




Note: The connectionIntegrity field is set by the Broker, so it does not reflect the integrity of the connection between the receiving Broker client and its Broker.

The pubNetAddr Envelope Field

This six-byte, read-only envelope field is set by the Broker and contains the IP address and port number of the event's publisher. The first four bytes contain the publisher's IP address in network byte-order. The next two bytes contain the publisher's port number in network byte-order.

The presence of this read-only envelope field is controlled by the Broker configuration file. This envelope field is disabled by default, by you can enable it using the following steps:

1 Edit the Broker configuration file and add the following line:

pub-net-address-in-envelope=1

2 Save the file.

3 Restart the Broker Server.

Note: This will enable the pubNetAddr envelope field for all Brokers within the Broker Server.

4 For complete information on the Broker configuration file, see Administering webMethods Broker document.

The route Envelope Field

The route read-only envelope field is a sequence of structures that contain event forwarding information. This field is only set on those events which are forwarded from one Broker to another Broker. This envelope field will not be set if both the publishing and receiving clients are both connected to the same Broker. Each structure in the sequence has the format shown in the table below.

"Export" All the connections used to transport the event had an encryption strength of ENCRYPT_LEVEL_US_EXPORT or greater.

"US Domestic" The event traveled exclusively over connections with an encryption strength of ENCRYPT_LEVEL_US_DOMESTIC.

Type Member Name Description

string broker Name of the Broker.

date recvTime Time the Broker received the event from the publishing client or the other Broker.

Value Meaning



The values for route[0] will represent the originating Broker. Each time the event is forwarded to another Broker, an additional structure will be added to the route sequence.

For more information on Broker-to-Broker communication, see Administering webMethods Broker

Specifying Field Names

Many of the methods offered by BrokerEvent require a field name parameter. How you specify a field name depends on the type of field being referenced and the method being used. The example below shows a hypothetical event type that contains several different types of data fields.

Note: Event field names are case sensitive.

Sample::StructEvent { string title; float seqA[]; int seqB[][]; struct structA{

BrokerDate date; int seqC[] [];

} struct structB{

BrokerDate time; struct emp {

string name; string ssn;

} } struct structC[] {

BrokerDate date; int seqD[] [];

}

The table below shows the field names you could specify to reference the various fields within the event type shown in the example above.

date enqueueTime Time the Broker enqueued the event for the next Broker.

Field Name Description Related BrokerEvent Methods

title The string value. getStringValue setStringValue

seqA The entire sequence of float values.

getSequenceField setSequenceField

Type Member Name Description



seqA[0] First float value in seqA getFloatField setFloatField

seqA[] Used to obtain the field's type when the number of elements in the sequence is not known.

getFieldType

seqB[0][0] First int value in seqB. getIntField setIntField

seqB[][] Used to obtain the field's type when the number of elements in the sequence is not known.

getFieldType

structA The entire structA structure. getStructFieldAsEvent setStructFieldFromEvent

structA.date BrokerDate value within structA.

getDateField setDateField

structA.seqC[0][0]

First int value in seqC, within structA.

getIntegerField setIntegerField

structA.seqC[][] Used to obtain the field's type when the number of elements in the sequence is not known.

getFieldType

structB The entire structB structure. getStructFieldAsEvent setStructFieldFromEvent

structB.time BrokerDate within structB. getDateField setDateField

structB.emp The structure within structB. getStructFieldAsEvent setStructFieldFromEvent

structB.emp.name The string within the emp structure, within structB.

getStringField setStringField

structC The entire structure sequence structC.

getStructSeqFieldAsEvents setStructSeqFieldFromEvents

structC[0].date BrokerDate within the first structure in the structC sequence.

getDateField setDateField

structC[].date Used to obtain the field's type when the number of elements in the sequence structC is not known.

getFieldType

structC[0].seqD[0][0]

First int value in seqD, within the first structure in the structC sequence.

getIntegerField setIntegerField




structC[].seqD[][]

Used to obtain the field's type when the number of elements in the sequences structC and seqD are not known.

getFieldType



5 Subscribing to and Receiving Events

Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90

Event Subscriptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90

Receiving Events in the Get-Events Model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93

Getting Events using the poll Method . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101

Detecting Deadletters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104



Overview

This chapter describes the webMethods Broker Java API for subscribing to, receiving and processing events. Reading this chapter will help you to understand:

How to register and cancel event subscriptions.

How subscription identifiers are created and used with subscriptions.

How to retrieve events from the Broker using BrokerClient.getEvent or BrokerClient.getEvents.

How to use the redelivery counter to detect events that your client has received more than once.

How to retrieve events from the Broker using BrokerClient.poll.

How to create a subscription that captures deadletters.

Event Subscriptions

In order for your application to be able to receive and process events, it must first create a BrokerClient. Then, any event that is permitted by the client group to which the BrokerClient belongs can be retrieved by your application.

Note: You do not have to register any event subscriptions to receive a delivered event. For more information on delivering events, see “Delivering Events” on page 133.

To receive published events, your application must first use the BrokerClient to subscribe to the event types that it wants to receive. Event subscriptions are always made within the context of a particular BrokerClient object.

Note: Event types are defined with Software AG Designer, described in the Software AG Designer Online Help. Note that event types are known as document types in Designer and other webMethods components.

A single BrokerClient can make multiple subscription requests, so subscriptions are distinguished by the unique combination of the event type name and an optional filter string. Filters, covered in “Using Event Filters” on page 157, allow you to receive only those events that contain certain data in which you are interested. If a BrokerClient requires two subscriptions for the same event type name, a different filter string must be specified for each subscription.

You can use the BrokerClient.getSubscriptions method to obtain the names of all the open subscriptions for a Broker client.



Limits on Subscriptions

The client group to which the BrokerClient object belongs might limit the event types to which the client can subscribe. See “Client Groups” on page 39 for more information. The example below contains an excerpt from the subscribe1.java sample application that shows the use of the BrokerClient.canSubscribe method to check for event subscription permission. This method requires a single parameter; an event type name.

BrokerClient c; boolean can_subscribe; . . . try { can_subscribe = c.canSubscribe("Sample::SimpleEvent"); catch (BrokerException ex) { System.out.println("Error on check for can subscribe\n"+ex); return;

} . . .

You can also use the BrokerClient.getCanSubscribeNames method to obtain the names of all the event types to which a Broker client can subscribe.

Subscribing to Events

Your application can subscribe to an event by calling one of the BrokerClient.newOrReconnect methods. The example below contains an excerpt from the subscribe1.java sample application that shows the use of the BrokerClient.newSubscription method. This method accepts these parameters:

An event type name.

An event filter string or null if event filtering is not wanted. Filters are described in “Using Event Filters” on page 157.

BrokerClient c; . . . /* Make a subscription */ try {

c.newSubscription("Sample::SimpleEvent",null); } catch (BrokerException ex) {

System.out.println("Error on create subscription\n"+ex); return;

} . . .

Uniqueness of Subscriptions

Each subscription that your BrokerClient registers is considered to be unique, based on the event type name and filter specified. After you have registered a subscription for a particular event type name and filter combination, any attempts to register another subscription with the same combination will be ignored.



Note: The BrokerClient.newSubscription method will not throw an exception if you attempt to register the same subscription more than once, it will simply ignore the request.

You can use the BrokerClient.doesSubscriptionExist method to determine whether a subscription has already been registered.

Cancelling a Subscription

Your application can cancel an event subscription by calling the BrokerClient.cancelSubscription method. The example below contains an excerpt from the subscribe1.java sample application that shows how you can use this method. This method accepts these parameters:

The event type name, which can optionally contain a wildcard at the end.

The event filter string that was specified with the original specification. A null value can be specified if event filtering was not specified in the original subscription. Event filters are described in “Using Event Filters” on page 157.

BrokerClient c; . . . /* Cancel the subscription */ try {

c.cancelSubscription("Sample::SimpleEvent",null); } catch (BrokerException ex) {

System.out.println("Error on canceling subscription\n"+ex); return;

} . . .

Using Wildcards

To register or cancel a subscription for multiple event types, you can use a single wildcard character, *, at the end of the event type name. To subscribe to all the event types within the scope of Sample, you could use the following event type name:

Sample::*

If you use wildcards in the event type name, the following restrictions apply:

Only those event types that your client has permission to subscribe to will be included in the subscription.

Wildcards cannot be used with any event type within the scope of Broker::Trace or Broker::Activity.

If a filter string is specified for the subscription, it might not contain any data fields. The filter string might contain envelope fields, however.



Receiving Events in the Get-Events Model

The simplest way to retrieve events is to use the get-events model, which involves these steps:

1 Create a BrokerClient object.

2 Use the BrokerClient to subscribe to one or more event types. If your client only expects to receive delivered events, no subscriptions are necessary.

3 Enter a processing loop in which the BrokerClient.getEvent method is called to retrieve the next event.

4 Extract the fields that you want from each received event using the methods described in “Creating and Initializing Events” on page 67. Return to step 3 and receive the next event.

5 Call BrokerClient.destroy when you are finished.

You can also retrieve events using the poll method or the callback method. For more information, see “Getting Events using the poll Method” on page 101 or “Using the Callback Model” on page 59 respectively.

The example below contains an excerpt from the subscribe1.java sample application that shows the use of theBrokerClient.getEvent method. This method accepts a single parameter; the number of milliseconds to wait for an event, if none are currently available. This can be set to -1 if you want to block indefinitely.

. . . BrokerClient c; BrokerEvent e; . . . /* Loop getting events */ count = 1; while(count <= num_to_receive) {

try { e = c.getEvent(MAX_EVENTS);

} catch (BrokerException ex) { System.out.println("Error on getting event\n"+ex); return;

} ++count;

} . . .

Note: The BrokerClient.getEvent method automatically acknowledges all outstanding events for the Broker client. See “Using Sequence Numbers” on page 145 for information on acknowledging events.

Getting Multiple Events

Your application can use the BrokerClient.getEvents method to retrieve up to 160 events with a single call, instead of calling BrokerEvent.getEvent to retrieve events one at a time.



Using the BrokerClient.getEvents method, the subscribing client is given events only once per session. To get events again before acknowledging, disconnect your subscriber and connect again.

The example below shows how the subscribe1.java sample application might be altered to use the BrokerClient.getEvents method. This method accepts these parameters:

The maximum number of events you want to be returned (up to 160).

The number of milliseconds to wait for an event, if none are currently available. This can be set to -1 if you want to block indefinitely.

long receive_attempts = 10; long number_received; BrokerClient c; BrokerEvent e[]; . . . /* Loop getting events */ count = 1; while(count <= num_to_receive) {

try { e = c.getEvents(20, -1);

} catch (BrokerException ex) { System.out.println("Error on getting events\n"+ex); return;

} /* process the received events */ . . . ++count;

} . . .

Note: The BrokerClient.getEvents method automatically acknowledges all outstanding events for the Broker client. See “Using Sequence Numbers” on page 145 for information on acknowledging events.

Synchronous Get Events

To specify a synchronous get events using any of the BrokerClient.getEvent or BrokerClient.getEvents methods, you must use the BrokerClient.SYNCHRONOUS definition as the timeout value for the methods.

If the Broker receives the "events" protocol with its flag set to "synchronous" then the Broker will either:

Return any available events up to the maximum number of requested events

Immediately return indicating that no events are available.

When there are no events available, the Broker will not submit a pending request for events on behalf of the client.

If the Broker API requests a synchronous get events, one of the following can occur:



If the Broker does not return with a response within the default Broker timeout, then a BrokerTimeoutException will be thrown.

If the Broker returns with events, then the events are returned by the get events method.

If the Broker returns an indication that no events are available then the Broker client's get events methods will return both of the following:

A null for the Brokerclient.getevent methods

A zero-length BrokerEvent array for the BrokerClient.getEvents methods

The example below shows the use of synchronous get events using the BrokerClient.getEvent and BrokerClient.getEvents methods. To specify synchronous get events, set the timeout value to the BrokerClient.SYNCHRONOUS.

// Example 1 BrokerClient client; BrokerEvent event = client.getEvent(BrokerClient.SYNCHRONOUS); If (event != null) {

process(event); }

// Example 2 BrokerClient client; BrokerEvent[] events = client.getEvents(10, BrokerClient.SYNCHRONOUS); If (events.length > 0) {

process(events); }

For more information, see the BrokerClient.getEvent and BrokerClient.getEvents methods.

Detecting Redelivered Events

When you enable the Broker's redelivery counting feature in the connection descriptor, your client can detect whether it has received an instance of a particular event more than once. A redelivery is indicated if an event's redelivery count is greater than zero.

In the BrokerConnectionDescriptor, you enable the redelivery counter, and use it in one of two modes, manual or automatic. To able the redelivery counter, you use the setRedeliveryCountEnabled method. The default mode is manual. In this mode your client must explicitly increment the redelivery counter.

To enable automatic mode, call setAutomaticRedeliveryCount after you call setRedeliveryCountEnabled. In automatic mode, the Broker automatically increments the redelivery counter when it re-sends an event to a client.

In either mode, the Broker sets the counter to zero the first time it sends an instance of an event to the client.

The following table summarizes the methods associated with the redelivery feature:



Note: The redelivery counter applies only to guaranteed events. Volatile events always have a redelivery count of -1. Additionally, if a client does not enable redelivery counting, all events that it receives will have a redelivery count of -1.

Manual Redelivery Counting

When you enable manual counting mode, your client must explicitly update the counter by calling BrokerClient.incrementRedeliveryCount after it successfully receives an event from the Broker. (Only the client session that receives an event can update the redelivery count for that event.)

After incrementing the counter, your client must immediately dispatch the event and the counter value its user code. The user code must accept the redelivery count (an integer) and take appropriate steps to process the event if the value of the counter is greater than zero.

The following snippet illustrates how you would count redeliveries in manual mode.

static String broker_host = "localhost"; static String broker_name = null; static String client_group = "sample";

BrokerConnectionDescriptor d; BrokerClient c; BrokerEvent e; long rsn; boolean rd_mode = true; int rd_count;

Method Description

BrokerConnectionDescriptor. setRedeliveryCountEnabled

Enables the redelivery counter in the connection descriptor.

BrokerConnectionDescriptor. getRedeliveryCountEnabled

Returns the current value of the redelivery counting option from the connection descriptor.

BrokerConnectionDescriptor. setAutomaticRedeliveryCount

Sets the redelivery counting option to automatic mode. The default value is manual mode.

BrokerConnectionDescriptor. getAutomaticRedeliveryCount

Returns the current value of the automatic redelivery option from the connection descriptor. You use this method to determine whether the redelivery counter is configured for automatic or manual mode.

BrokerEvent.getRedeliveryCount Returns the current value of the redelivery counter.

BrokerClient.incrementRedeliveryCount Increments the redelivery counter by one.



. . . /* -----------------------------------------------*/ /* Create descriptor and enable Manual Redelivery */

try { d = new BrokerConnectionDescriptor; d.setRedeliveryCountEnabled(rd_mode); } catch (BrokerException ex) {

System.out.println("Error on create descriptor\n"+ex); return;

} /* ----------------------------------------------- */ /* Create client using connection descriptor */

try { c = new BrokerClient(broker_host, broker_name,

null, client_group, "Subscriber Sample #1",d);

} catch (BrokerException ex) { System.out.println("Error on create client\n"+ex); return;

} . . . /* -------------------------------------------------*/ /* Get event, update count, pass event to user code */

while (dispatchingDocuments() == true) { e = BrokerClient.getEvent(); rsn = e.getReceiptSequenceNumber(); rd_count = e.getRedeliveredCount(); if (c.incrementRedeliveryCount (rsn) != OK)

break; if (dispatchToUserCode(e, rd_count) == OK) {

c.acknowledge(rsn); }

} . . .

Automatic Redelivery Counting

If the client is using automatic redelivery counting mode, the Broker automatically updates the redelivery counter when delivers an event to a client. As in manual mode, the redelivery counter is set to zero the first time the event is delivered to a client. If the Broker resends the event to the client, it increments the event's redelivery counter before sending the event out.

The way in which a client uses automatic redelivery counting mode is nearly the same as it would use manual mode. As you can see by the following snippet, the code is identical to the manual mode example on above in “Manual Redelivery Counting” on page 96, except that 1) the client sets the connection descriptor automatic mode and 2) it omits the call to the incrementRedeliveryCount method.

static String broker_host = "localhost"; static String broker_name = null; static String client_group = "sample";



BrokerConnectionDescriptor d; BrokerClient c; BrokerEvent e; long rsn; boolean rd_mode = true; int rd_count;

. . . /* -----------------------------------------------*/ /* Create descriptor and enable Automatic Redelivery */

try { d = new BrokerConnectionDescriptor; d.setAutomaticRedeliveryCount(rd_mode); } catch (BrokerException ex) {

System.out.println("Error on create descriptor\n"+ex); return;

} /* ----------------------------------------------- */ /* Create client using connection descriptor */

try { c = new BrokerClient(broker_host, broker_name,

null, client_group, "Subscriber Sample #1",d);

} catch (BrokerException ex) { System.out.println("Error on create client\n"+ex); return;

} . . . /* -------------------------------------------------*/ /* Get event, update count, pass event to user code */

while (dispatchingDocuments() == true) { e = BrokerClient.getEvent(); rsn = e.getReceiptSequenceNumber(); rd_count = e.getRedeliveredCount(); if (dispatchToUserCode(e, rd_count) == OK) {

c.acknowledge(rsn); }

} . . .

As shown above, your Broker client dispatches the event and the redelivery count to user code. The user code must accept the redelivery count (an integer) and take appropriate steps to process the event if the value of the counter is greater than zero.

Redelivery and Older Versions of webMethods Software

If a client attempts to enable redelivery counting while running against a Broker running a versions prior to 6.1, the client will receive a BrokerInsufficientVersionException when it attempts to create a BrokerClient.



Subscription Identifiers

The webMethods Broker API allows you to associate an arbitrary value, called a subscription identifier, with an event subscription. You can use subscription identifiers to quickly determine how a retrieved event is to be processed. You might also find it helpful to use subscription identifiers if your application plans to use the callback model for retrieving and processing events. The callback model is described in “Using the Callback Model” on page 59.

Subscription IDs do not uniquely identify a particular subscription, so you can create different subscriptions and with the same subscription ID.

Note: You cannot register the same subscription with more than one subscription ID. This means that if you register a particular subscription for a BrokerClient and assign it a subscription ID of 1, any attempt to register the same subscription with a different subscription ID will be ignored. See “Uniqueness of Subscriptions” on page 91 for more information on what differentiates one subscriptions from another.

Specifying Subscription IDs

The example below illustrates the use of the BrokerClient.newSubscription method to associate two subscription identifiers with two different subscriptions. This version of the BrokerClient.newSubscription method accepts these parameters:

The subscription identifier.

An event type name.

An event filter string or null if event filtering is not wanted. Filters are described in “Using Event Filters” on page 157.

Assigning subscription identifiers

. . . /* Make subscription #1*/ try {

c.newSubscription( 1, "Sample::SimpleEvent1",null); } catch (BrokerException ex) {


} /* Make subscription #2*/ try {

c.newSubscription( 2, "Sample::SimpleEvent2",null); } catch (BrokerException ex) {


} . . .



Obtaining Subscription Identifiers

The example below shows how you could use the BrokerEvent.getSubscriptionIds method to obtain the subscription identifier of a retrieved event.

Note: If the filter string specified for two or more subscriptions have overlapping criteria, it is possible for a retrieved event to be associated with more than one subscription identifier. For more information on event filters, see “Using Event Filters” on page 157.

This example assumes that the subscriptions described in the example in “Specifying Subscription IDs” on page 99 have already been made and that there is only one subscription identifier associated with any retrieved event. The BrokerEvent.getSubscriptionIds method accepts no parameters.

Note: Events that are delivered to your Broker client do not have subscriptions or subscription IDs. For more information on delivering events, see “Delivering Events” on page 133.

. . . BrokerClient c; BrokerEvent e; int subscriptions[]; ... while(1) {

try { e = c.getEvent(-1);

} catch (BrokerException ex) { System.out.println("Error on getting event\n"+ex); return;

} /* get the event’s subscription identifier */ subscriptions = e.getSubscriptionIds(); if((subscriptions != null) && (subscriptions.length > 0)){

switch( subscriptions[0] ) { case 1:

/* process Sample::SimpleEvent1 . . . */ break;

case 2: /* process Sample::SimpleEvent2 . . .*/ break;

default: break;

} }

} . . .

Generating Subscription Identifiers

You application can generate subscription identifiers itself or it can call one of the following webMethods Broker API methods to generate a subscription identifier.



The BrokerClient.makeSubId method creates a subscription identifier for a specified client. The first time it is called for a particular BrokerClient, it will return a value of 1. The second time it is called for the same BrokerClient, it will return a value of 2, and so on. The subscription identifiers are not guaranteed to be unique if your application disconnects and reconnects the BrokerClient, as described in “Disconnecting and Reconnecting” on page 43.

You can use the BrokerClient.makeSubId method to create unique subscription identifiers for Broker clients that you intend to disconnect and reconnect. This method contacts the Broker and looks up all the existing subscription identifiers in use by your application. It then assigns a subscription identifier that is guaranteed to be unique for all Broker clients that you might use. Another important feature is that after calling this method once, all subsequent calls to BrokerClient.makeSubId will return unique subscription identifiers.

BrokerSubscription Objects

The BrokerSubscription object provides a convenient way to refer to and manage subscriptions by defining the following three subscription attributes as data members:

The event's subscription identifier.

The event's name.

An event filter string, or null if event filtering is not wanted. Filters are described in “Using Event Filters” on page 157.

BrokerSubscription objects are used by the following webMethods Broker API methods:

BrokerClient.cancelSubscription method.

BrokerClient.cancelSubscriptions method.

BrokerClient.getSubscriptions method.

BrokerClient.newOrReconnect method.

BrokerClient.newSubscriptions method.

Getting Events using the poll Method

You can use the BrokerClient.poll method to simultaneously poll the queues of multiple Broker clients with a single thread. Unlike the "get events" model, where clients check their queues in serial fashion and block for a specified interval if their queue is empty, the poll method enables an application to dispatch a client to its queue only if there are events there for it to retrieve. This approach results in a more efficient process that wastes fewer cycles on non-productive work (i.e., blocking while a client attempts to retrieve events from an empty queue).

Because the poll method uses a single thread to monitor the queues of multiple clients, it is also easier to implement than spawning individual threads for each client.



The BrokerClientPoll Object

A BrokerClientPoll object maintains information that the polling process takes as input and returns as output. To use the polling model, an application must create a BrokerClientPoll object for each Broker client whose queue the application will poll.

When an application instantiates a BrokerClientPoll object, it must provide two parameters to the constructor, 1) the BrokerClient whose queue the application wants to poll and 2) the GET_EVENTS flag, which tells the poll method to poll for events.

Note: Despite its name, the GET_EVENTS flag does not cause the poll method to actually retrieve events from a client's queue. Your application code must do that. The poll method merely indicates that events are available and that the getEvents method will not block if executed.

Key Methods used in the Polling Model

The following table summarizes the primary methods and constructors associated with the polling model. For a complete list, see BrokerClientPoll on page 273.

Using the poll Method

The following procedure describes the general steps you use the poll method to retrieve events.

1 Create the Broker clients (e.g., BrokerClient[]) whose queues you want to poll.

2 Generate an array containing a BrokerClientPoll object for each client in BrokerClient[].

3 Call the BrokerClient.poll method and pass in the BrokerClientPoll[] and a time-out interval (in milliseconds). This method will check the queue of each client represented BrokerClientPoll[]. If the method discovers at least one event in a client's queue, it sets a flag in that client's BrokerClientPoll object. If the method does not find an event in any of the client queues, it continues to poll until 1) one or more events arrive, 2) the specified timeout interval expires, 3) the thread is interrupted, whichever occurs first.

Method/Constructor Description

BrokerClientPoll The constructor that generates a BrokerClientPoll object for a specified Broker client.

BrokerClient.poll Polls the Broker for events in queues belonging to a specified set of Broker clients, and returns the BrokerClientPoll object for each client that has one or more events in its queue.

BrokerClientPoll.getBrokerClient

Returns the BrokerClient associated with a BrokerClientPoll object.



4 Loop through the BrokerClientPoll[] that the poll method returns and retrieve the events from the queues of the clients represented in that array. (The array will not contain clients whose queues were empty.)

Important! The queues of the clients in the array have already been primed using prime(1). Your application code does not need to re-prime the queues unless you want it to fetch more than a single event.

A Polling Example

The following snippet illustrates how you would code the steps described above.

static String broker_host = "localhost"; static String broker_name = null; static String client_group = "sample"; int N = numberOfClients;

. . . /* --------------------------------------------------------*/ /* Allocate the array for BrokerClients */

BrokerClient[] c = new BrokerClient[N] /* --------------------------------------------------------*/ /* Create BrokerClients */ . . . /* ---------------------------------------------------------*/ /* Allocate array for BrokerClientPoll Objects */

BrokerClientPoll[] poll = new BrokerClientPoll[N]; /* ---------------------------------------------------------*/ /* Create BrokerClientPoll objects for each BrokerClient */

for (int i = 0; i < N; i++) { poll[i] = new BrokerClientPoll(c[i], BrokerClientPoll.GET_EVENTS, null); /* ----- Prime the client -------------------------- */

c[i].prime(NUM_TO_PRIME); }

/* ----------------------------------------------------------*/ /* Poll the queues of clients identified in BrokerClientPoll[] for (;;) {

BrokerClientPoll[] result = BrokerClient.poll(poll, -1); /* ----------------------------------------------------------*/ /* Get events for BrokerClients identified in results array */

for (int i = 0; i < result.length; i++) { if (result[i].isReady(BrokerClient.GET_EVENTS)) {

BrokerEvents[] events = result[i].getBrokerClient().getEvents(MAX, 0);



/* ----- Re-prime the client ---------------- */ result[i].getBrokerClient().prime(NUM_TO_PRIME);

} }

}

Detecting Deadletters

If a Broker receives an event for which it has no subscribers, it discards the event unless a deadletter subscription exists for that event type. A deadletter subscription enables you to trap events for which no subscriptions exist. Among other things, trapping deadletters can help to quickly identify and resolve discrepancies between a published event and the filtering criteria specified by a subscriber.

Creating a Deadletter Subscription

To subscribe to deadletters, you use the BrokerClient.newSubscription method. In the filter parameter for this method, you specify the DeadLetterOnly hint.

As shown in the following examples, you can use wildcards to specify the types of events for which you want to receive deadletters.

The following code fragment shows how you would create a deadletter subscription for a specific event type.

BrokerClient c; . . . /* Create a deadletter subscription for an event type*/ try {

c.newSubscription("APITest::SimpleEvent","{hint:DeadLetterOnly})"; catch (BrokerException ex) {


} . . .

The following code fragment show how you would use a wildcard character to create a deadletter subscription to all events in a particular namespace.

BrokerClient c; . . . /* Create a deadletter subscription for all events in a namespace*/ try {

c.newSubscription("APITest::*","{hint:DeadLetterOnly})"; catch (BrokerException ex) {


} . . .

The following code fragment show how you would use the wildcard character to create a deadletter subscription for all events.



BrokerClient c; . . . /* Create a deadletter subscription for all event types*/ try {

c.newSubscription("*","{hint:DeadLetterOnly})"; catch (BrokerException ex) {


} . . .

Deadletter Subscriptions and Filters

Be aware that when you create a deadletter subscription, you are subscribing to all events of the specified type(s). You cannot filter events in a deadletter subscription. If you specify the DeadLetterOnly hint and a filter in the same subscription, the filter is ignored.

Deadletter Permissions and Persistence

With respect to permissions and persistence, the following points apply to deadletter subscriptions:

A deadletter subscription is subject to the same permission requirements as a regular subscription. That is, a client can receive deadletters for only the events on its can-subscribe list. If a client specifies an event type using wildcard characters, that client will receive only those deadletters that coincide with its can-subscribe list.

Persistence of deadletter events is determined by the normal rules of client types and event types.

Deadletter subscriptions apply to both published and delivered events. If the Broker receives a delivered event that has been addressed to a non-existent client, the Broker will deposit that event in the deadletter queue if one exists for the event type.

How Deadletter Subscriptions Relate to Regular Subscriptions

The following describes the way in which deadletter subscriptions are affected by regular subscriptions for the same event type.

If the Broker permits identical subscriptions to a regular event and a deadletter event. In this situation, the deadletter subscribers simply never receive any events.

If a wildcard definition in a deadletter subscription overlaps with that of a regular subscription, the Broker distributes events that match the regular subscriptions to the appropriate clients and then routes the others to the deadletter subscriber.

An event type can have more than one deadletter subscriber.

Deadletter Behavior in a Territory

The following points describe the behavior of deadletter subscriptions within a territory.



Deadletter subscriptions are implicitly "local-only," meaning that deadletter events published by one Broker are not forwarded to deadletter subscribers on other Brokers.

To ensure that an instance of an event can be captured as a deadletter by any Broker to which it might be forwarded, you need to create a deadletter subscription for that event type on each Broker in the territory.


6 Using Request-Reply

Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 108

The Request-Reply Model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 108

The Requestor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 110

The Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114



Overview

This chapter describes the webMethods Broker Java API for implementing applications that use the request-reply event processing model. Reading this chapter will help you to understand:

The use of event tag fields to match request events that are sent with reply events that are received.

The various types of reply events.

Using get-event, callback, and the BrokerClient.publishRequestAndWait approaches in implementing a requestor application.

Using the reply methods to implement a request server application.

The Request-Reply Model

You can use the request-reply model for applications that publish or deliver a request event to a server application which is expected to return a reply event. The reply event can contain data or can simply be an acknowledgment with no data.

Request and reply events and their tag fields

Request Events and the Tag Field

A tag envelope field is set by your requestor application to identify the request event that it is sending. When a server application receives the request event and prepares the reply event, it ensures that the same tag field is set for the reply as was received on the request event. If your requestor sends several different request events, it should set each with a different tag field. When your requestor receives a reply event, it can check the tag field to determine the original request with which the reply is associated.



Getting and Setting the Tag

Use the BrokerEvent.getTag method to obtain the tag field from an event. Use the BrokerEvent.setTag method to set an event's tag field.

Using the trackId Field

The trackId envelope field can be set by a publishing client application to a unique identifier that will allow the event to be tracked. The use of this envelope field allows an event that is received and then re-published to still be tracked. This envelope field also allows you to track several events that can be associated with a single logical transaction.

Note: If trackId envelope field is not set, any of the Broker Server methods for delivering reply events will automatically set it to the value contained the pubId envelope field.

Reply Events

The content of a reply events can vary, depending on the design of the requestor and server applications. The request event's infoset defines the reply event that is expected.

A reply event can take one of the following forms:

A null event that has no data.

An acknowledgment that indicates the operation was successful.

A single reply event containing application-defined data.

A series of reply events containing application-defined data.

An error reply.

If a series of reply events are returned, the appSeqn and appLastSeqn envelope fields can be accessed to determine the event's sequence position. See “Envelope Fields” on page 80 for more information.

Determining a Reply Event's Type

The following methods are provided to help your client application determine what type of reply event has been received.

Use the BrokerEvent.isAckReply method to determine whether an event is an acknowledgment reply.

Use the BrokerEvent.isErrorReply method to determine whether an event is an error reply.

Use the BrokerEvent.isLastReply method to determine whether an event is the last reply in a sequence.

Use the BrokerEvent.isNullReply method to determine whether an event is a null reply.



The Requestor

You have several processing models to choose from when designing a requestor application. These design alternatives include:

Use BrokerClient.publish to send the request event, use BrokerClient.getEvent to receive possible reply events, and check each event received for a matching tag.

Create a callback object for the response event and register it with BrokerClient.registerCallbackWithTag, specifying the tag you will use. Use BrokerClient.publish to send the request event and then use one of the Broker Server dispatching methods to dispatch received events.

Use BrokerClient.publishRequestAndWait to send the request event and wait until a reply event is received.

The following example shows the code that implements the following preliminary steps:

1 Create a BrokerClient object.

2 Check for publication permission for the request event type.

3 Check for subscription permission for the reply event type. This is done even though the reply event will be delivered because it indicates if the requestor's client group will allow it to receive the reply event type.

4 Create a request BrokerEvent object.

5 Create a tag for the request event using the BrokerClient.makeTag method.

6 Set the request event's tag field using the BrokerEvent.setEventTag method.

. . . BrokerClient c; BrokerEvent e; boolean permission; int request_tag; . . .

/* Create a client */ try {



} /* Check if can subscribe */ try {

permission = c.canSubscribe("Sample::Reply"); } catch (BrokerException ex) {

. . . } /* Check if can publish */ try {

permission = c.canPublish("Sample::Request"); } catch (BrokerException ex) {

. . . }



/* Create the request event */ try {

e = new BrokerEvent(c, "Sample::Request"); } catch (BrokerException ex) {

. . . } /* Create tag and set request event’s tag field */ request_tag = c.makeTag(); try {

e.setTag(tag); } catch (BrokerException ex) {

. . . }

. . .

Using the Get-event Approach

After the preliminary processing described in the example above in “The Requestor” on page 110 has been completed, the get-event design involves these steps:

1 Use BrokerClient.publish to publish the request event.

2 Enter a processing loop and receive events with BrokerClient.getEvent.

3 Use BrokerEvent.getTag to check each received event for a tag that matches the request event's tag.

The following example illustrates receiving a reply event with BrokerClient.getEvent:

. . . BrokerClient c; BrokerEvent e; boolean done; int received_tag; long request_tag; . . . /* Create BrokerClient, check subscription and publish permissions, * create request BrokerEvent, create tag, set tag field */ . . . /* Publish the request */ try {

c.publish(e); } catch (BrokerException ex) {

. . . } /* Loop getting events */ done = 0; while(!done) {

try { /* get an event */ e = c.getEvent();


} try { /* get the event’s tag */

received_tag = e.getTag();




} /* see if event matches request */ if (request_tag == received_tag) {

if (e.isNullReply()) /* handle null reply */

} else if (e.isErrorReply()) { /* handle error reply */

} else { /* process the event */ . . .

} done = e.isLastReply();

} } . . .

Callbacks with Tags

After the preliminary processing described in the example above in “The Requestor” on page 110 has been completed, the callback design involves these steps:

1 Use BrokerClient.publish to publish the request event.

2 Use BrokerClient.registerCallback to register a general callback object.

3 Use BrokerClient.registerCallbackForTag to register a specific callback object for the reply event with the request event's tag.

4 Use one of the callback dispatching methods, described on “Dispatching Callback Methods” on page 64, to receive events and dispatch the appropriate callback object's event handling method.

The following example illustrates receiving a reply event with a callback object:


SampleCallback1 general_callback = new SampleCallback1(num_to_receive);

SampleCallback2 specific_callback = new SampleCallback2(num_to_receive);

. . . /* Publish the request */ try {


. . . } /* Register general callback */ try {


System.out.println("Error on registering general callback\n"+ex); return;

}



/* Register specific callback for the request_tag */ try {

c.registerCallbackForTag(request_tag, true, specific_callback,null);

} catch (BrokerException ex) { System.out.println("Error on registering specific callback\n"+ex); return;

} /* Dispatch loop */ try {

BrokerClient.dispatch(-1); } catch (BrokerException ex) {


} . . .

The following example illustrates the callback implementation:

public class SampleCallback2 implements BrokerCallback { . . .

/* Method to handle the webMethods Broker Server event callbacks. */ public boolean handleBrokerEvent(

BrokerClient client, BrokerEvent event, Object client_data)

{ if (event.isNullReply()) {

/* handle null reply */ System.out.println("Null reply received.\n");

} else if (event.isErrorReply()) { /* handle error reply */ System.out.println("Error reply received.\n");

} else { /* process the event */ . . .

} return true;

} }

Using publishRequestAndWait

After the preliminary processing described in the example above in “The Requestor” on page 110 has been completed, the callback approach involves these steps:

1 Use BrokerClient.registerCallback to register a general callback object.

2 Use BrokerClient.publishRequestAndWait to publish the request and wait for the reply. You can also use the BrokerClient.deliverRequestAndWait method if you want to send the request event to a specific Broker client.

Note: No event subscription is necessary in this model because the reply event will be delivered, not published.



The following example illustrates how to use BrokerClient.publishRequestAndWait:


BrokerClient c; BrokerEvent e, events[]; int i; SampleCallback1 general_callback =

new SampleCallback1(num_to_receive); . . . /* Register general callback */ try {


. . . } /* publish the request and wait for a reply */ try {

events[] = c.publishRequestAndWait(e, 6000); } catch (BrokerException ex) {

. . . } /* Process received events */ for( i = 0; i < events.length; i++) {

if (events[i].isNullReply()) { /* process null reply */

} else if (events[i].isErrorReply()) { /* process error reply */

} else { /* process reply */

} } . . .

The Server

Server applications must be allowed to subscribe to all of the event types that are to be processed. In response to a request event, servers must also be prepared to deliver a reply event of the expected type. Generally, your server application should follow these steps:

1 Check for permission to subscribe to the request event types.

2 Check for the appropriate reply event publishing permissions.

3 Retrieve an event and process it.

4 Deliver the appropriate reply event(s).



Checking Subscription and Publishing Permissions

The Server shown in the following example checks to see if it has permission to subscribe to the request event and to deliver the appropriate reply event. The BrokerClient.canPublish method is used to determine whether the Broker client has the necessary permissions to deliver the various reply events. In this example, the application expects that it might have to deliver the event types shown in the following table:

boolean permission; BrokerClient c; . . . /* Create a Broker client */ . . . /* Check if can publish reply */ try {

permission = c.canPublish("Sample::Reply"); } catch (BrokerException ex) {

. . . } if(!permission) {

System.out.println(“Permission to publish Sample::Reply denied.\n”); return;

} /* Check if can publish error reply */ try {

permission = c.canPublish("Adapter::error"); } catch (BrokerException ex) {


System.out.println(“Permission to publish Adapter::error denied.\n”); return;

} /* Check if can publish acknowledgement */ try {

permission = c.canPublish("Adapter::ack"); } catch (BrokerException ex) {


System.out.println(“Permission to publish Adapter::ack denied.\n”); return;

} /* Check if can subscribe to the request event */

Event Type Description

Adapter::error Used to indicate that an exception occurred in the processing of the event.

Adapter::ack Used if the infoset for Sample::Request specifies that a simple success or failure indication is all that is expected.

Sample::Reply Used if the infoset for Sample::Request defines a specific event type as a response.



try { permission = c.canSubscribe("Sample::Request");


} if(!permission) {

System.out.println(“Cannot subscribe to Sample::Request denied.\n”); return;

}

/* Subscribe to the request event */ try {

c.newsubscription("Sample::request", null); } catch (BrokerException ex) {

. . . } . . .

Processing Request Events

Your server application has all of the usual options for receiving and processing events. It can use the BrokerClient.getEvent method to receive events within a manually coded loop, described in Chapter 4. If your server subscribes to several request event types, it can use the callback model described in “Using the Callback Model” on page 59.

The server application can also associate an identifier with each of the subscriptions that it registers. When an event is received, the server application can easily determine how to process the request event. See “Subscription Identifiers” on page 99 for more information.

The following example shows an excerpt of a server application that uses BrokerClient.getEvent method to receive an event and determines if it is a request event.

. . . BrokerClient c; BrokerEvent e; int n, count = 200; String event_type_name; . . . /* Loop getting events */ n = 1; while(n < count) {

try { e = c.getEvent(-1);


} /* Check if it is a request */ try {

event_type_name = e.getEventTypeName(); } catch (BrokerException ex) {

. . . } if ((event_type_name != null) &&



(event_type_name.equals("Sample::Request")) { /* Process the request (see following excerpts) */ . . .

Delivering Replies

After you have processed a request event, you can use one of several methods to deliver the appropriate type of reply event.

Note: All of the following event delivery methods determine the destination identifier based on the pubId field of the original request event. None of these methods will return an error if the destination identifier refers to a Broker client that no longer exists.

Delivering Acknowledgment Replies

Your server application can deliver an acknowledgment reply if the infoset for the request event type defines that a simple success or failure indication is all that is required. When invoking the BrokerClient.deliverAckReplyEvent method, you can either specify a valid publish sequence number or specify a value of zero if you do not want to use publish sequence numbers. For more information, see “Using Sequence Numbers” on page 145.

. . . try { c.deliverAckReplyEvent(e,0); } catch (BrokerException ex) {

... }

. . .

Delivering Error Replies

The server application delivers an error reply to indicate that some sort of exception occurred while attempting to process the request event.

. . . BrokerEvent err[] = new BrokerEvent[1];

. . . /* Make error reply event */ err[0] = new BrokerEvent(c,"Adapter::error"); try {

c.deliverReplyEvent(e, err); } catch (BrokerException ex) {

. . . } . . .



Delivering Null Replies

The server application can deliver a null reply if the request was successfully processed and there is no data to be returned. When invoking the BrokerClient.deliverNullReplyEvent method, you can either specify a valid publish sequence number or specify a value of zero if you do not want to use publish sequence numbers. For more information, see “Using Sequence Numbers” on page 145.

. . . try {

c.deliverNullReplyEvent(e,”Sample::Reply”,0); } catch (BrokerException ex) {

. . . }

. . .

Delivering One or More Reply Events

The server application can deliver one or more reply events in response to a single request event, as shown in the following example.

. . . BrokerEvent replies[];

. . . /* prepare the reply events */ . . . /* deliver the replies */ try {

c.deliverReplyEvents(e, replies); } catch (BrokerException ex) {

. . . } . . .

Delivering Partial Replies

Your server application might need to deliver multiple reply events to satisfy a request event that it receives. If all of the reply event data cannot be read into memory or is not immediately available, the server can choose to send the reply events in batches rather than all at once.

The BrokerClient.deliverPartialReplyEvents method can be used in these cases. You must set the flag parameter to REPLY_FLAG_START, REPLY_FLAG_CONTINUE, or REPLY_FLAG_END to indicate the start, continuation, and end of the reply event sequence.

If all of the replies can be sent in one batch, simply set the flag to REPLY_FLAG_START_AND_END.

BrokerEvent reply_events[]; int token, flag; boolean done = false; . . .

/* prepare some reply events */ . . . flag = BrokerClient.REPLY_FLAG_START;



while(!done) { try {

token = c.deliverPartialReplyEvents(e, reply_events, flag, token);

} catch (BrokerException ex) { ...

} /* prepare more reply events */ . . . flag = BrokerClient.REPLY_FLAG_CONTINUE;

} flag = BrokerClient.REPLY_FLAG_END; /* prepare the last reply event */ . . . try {

token = c.deliverPartialReplyEvents(e, reply_events, flag, token);


} . . .




7 Transaction Semantics

Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122

About Transactional Client Processing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122

Using Broker Transaction Clients . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123



Overview

This chapter describes the webMethods Broker Java API for implementing applications that publish events using a transaction processing model. Reading this chapter will help you to understand transactional client processing with Broker.

About Transactional Client Processing

Transactional client processing facilitates publish, acknowledge, and get event functions within the context of a transaction.

Transaction processing allows your Broker client to group the events it publishes as a single unit of work called a transaction. A transaction either completes successfully, is rolled back to some known earlier state, or it fails. After all of the events that make up a transaction have been published, your Broker client then ends the transaction. A transaction can be ended by committing the transaction or aborting the transaction.

About the BrokerTransactionalClient Class

BrokerTransactionalClient class is a subclass of the BrokerClient class. BrokerTransactionalClient is a dedicated Broker Client that is exclusively used for transactional operations. Any task in the transactional operation environment should be done using the BrokerTransactionalClient. All of the existing BrokerClient methods that can be supported through the transactional class are supported by the BrokerTransactionalClient.

Transaction Support

A Broker transactional client initiates a transaction to publish, deliver or get the events that make up the transaction, then ends the transaction by committing or aborting the events. Other features of transaction support are:

After an ABORT operation, all request events in the transaction are discarded and will not generate any reply events, not even error replies.

All operations throw exceptions.

Any request event that generates an error on a COMMIT operation will cause subsequent events to be discarded. Furthermore, any changes from prior events will be rolled back. If an error occurs, an exception (either BrokerTxClosedException or BrokerInvalidTxException) will be thrown.



Transaction Context Timeline

Note: When the Broker Server is stopped and restarted, all open transactions prior to stopping the Broker Server will be aborted.

Using Broker Transaction Clients

To use Broker transaction clients, your application should follow these steps:

1 Obtain a third-party identifier (such as Tuxedo), which will be used with all publish, deliver, get and acknowledge events that will be part of the transaction. See “Obtaining an External Transaction ID” on page 124 for more information.

2 Begin the transaction. See “Beginning a Transaction” on page 124 for more information.



3 Publish, deliver, acknowledge, or get the events that make up the transaction. See “Operating within a Transaction” on page 124 for more information.

4 End the transaction, which can consist of a COMMIT or ABORT operation. See “Ending a Transaction” on page 127 for more information.

Obtaining an External Transaction ID

To generate an external transaction ID, use a third-party identifier, such as a Tuxedo. Refer to the documentation of the third-party identifier for more information.

Beginning a Transaction

To begin a transaction, first instantiate a new BrokerTransactionalClient object, then call the transactional client's beginTransaction method.

A unique Broker transaction ID that is specific to this newly opened transaction will be generated and returned as part of the new transaction object. This ID is unique to the specific Broker.

Note that this method can be null or can have an external transaction ID.

//unique Broker transaction ID long tid; //Create Transactional Client:

try { BrokerTransactionalClient pub = BrokerTransactionalClient.newOrReconnect (broker_host, broker_name,pubid, client_group_p, "TxTest-Pub", null); } catch (BrokerException ex) {

System.out.println ("Failed to create pub client\n" + ex); System.exit(1);

} //beginTransaction: // Start a transaction to publish events

try { tid = pub.beginTransaction(null);

} catch (BrokerException ex) { System.out.println ("Error on starting transaction " +ex); return;

} . . .

Operating within a Transaction

The transactional client object obtained at the beginning of the transaction is used to call all the supported transactional publish, deliver, and getEvent(s) methods of the BrokerClient object.

Your application publishes the events that make up the transaction in the manner described in “Publishing and Delivering Events” on page 131.



Note: Any event that is published with a transaction ID that is not known to the Broker will return an exception.

Whether or not your application will receive an acknowledgment event or a reply event for each event it publishes depends on how the event type was defined.

Note: Event types are defined with Software AG Designer. See the Software AG Designer Online Help for more information. Note that event types are known as document types in Designer.

Publishing a Transaction

Use the publish method to publish a transaction. This method publishes one event with the given transaction ID. When the event is published, it is sent to the Broker. The Broker then forwards the event to all its subscribing clients.

Note that the event is processed only after the transaction is committed. The following example contains an excerpt that shows the use of the publish method.

. . . // Define the BrokerClient to be used as a transactional client. BrokerTransactionalClient pub; // Define the event to be published BrokerEvent e; // Publish event try { pub.publish(e); } catch (BrokerException ex) { System.out.println ("Error on transactional publish" +ex); return; }

. . .

Publishing Multiple Events

Your application can publish several events with one call to the BrokerTransactionalClient.publish method that accepts an array of BrokerEvent objects. The following example contains an excerpt that shows the use of this method, which accepts a BrokerEvent array.

. . . // transactional multi-publish BrokerEvent[] er; try {

pub.publish (er); } catch (BrokerException ex) {

System.out.println ("Error on multi-publish" +ex); return;

} . . .



Whether or not your application will receive an acknowledgment event or a reply event for each event it publishes depends on how the event type was defined.

Note: Event types are defined with Designer. See the Software AG Designer Online Help for more information. Note that event types are known as document types in Designer.

Delivering a Transaction

To deliver a single event in one given transaction, use the deliver method. To deliver multiple events in one given transaction, use the deliver method. These methods send one event or multiple events to the Broker that will forward the events to the Client of the specified Client ID.

These methods require the following parameters:

dest_id. The client identifier of the Broker client that is to receive the events.

event(s). The BrokerEvent object or the array of BrokerEvent objects to be delivered.

Note that the event is processed only after the transaction is committed.

The following example contains an excerpt that shows the use of the deliver method for delivering a single event in one given transaction.

. . . // Do transacted Deliver static String subid = "Sub"; static String destid = "Sub";

for (int i=0; i<count; i++) {

try { pub.deliver (destid, e); } catch (BrokerException ex) { System.out.println ("FAIL TEST-A Error on tx deliver" +ex); return; } }

. . .

Getting Events

Your application can use the BrokerTransactionalClient.getEvents method to retrieve one or multiple events with a single call, instead of calling BrokerEvent.getEvent to retrieve events one at a time.

Using the BrokerTransactionalClient.getEvents method, the subscribing client is given events only once per session. To get events again before acknowledging, disconnect your subscriber and connect again.

The following example contains an excerpt that shows the use of the BrokerTransactionalClient.getEvents method for retrieving events in one given transaction. This method accepts these parameters:

max_events. The maximum number of events you want to be returned (up to 160).



int msecs. The number of milliseconds to wait for an event, if none are currently available. This can be set to -1 if you want to block indefinitely.

. . . // Create subscriber

try { sub = BrokerTransactionalClient.newOrReconnect(broker_host,

broker_name,subid, client_group_s, "TxTest-Sub", null);

} catch (BrokerException ex){ System.out.println ("Failed to create pub client\n" + ex); System.exit(1); }

// Loop getEvent and expect to receive events for (int i=0; i<count; i++){ try {

rc_ev = sub.getEvent(5000); System.out.println("Received Event\n" + rc_ev.toString());

} catch (BrokerException ex) { System.out.println ("Error on getEvent\n" + ex);

} }

. . .

Preparing Transactions For Commit

Before you commit the transactions, prepare the transactions for a two-phase commit. Use the prepare method to prepare a transaction, or use the prepareAll method to prepare a given list of transactions. If prepare fails, those transactions can only be aborted. The prepared transactions can be recovered by calling recover. Calling prepare or prepareAll methods is optional. You can directly commit or abort transactions without preparing them.

. . . // prepare transaction try {

long i = bc.beginTransaction("tx3"); System.out.println("Transaction id : " +i); BrokerEvent ev1 = new BrokerEvent(bc, eventtypename); bc.publish(ev1); bc.prepare("tx3"); } catch (BrokerException ex) { System.out.println ("Error on prepare" +ex); return; } } . . .

Ending a Transaction

Ending a transaction involves a COMMIT or ABORT operation.



Committing a Transaction

Use the commit method to commit an open transaction, or use the commitAll method to commit a given list of open transactions.

Note that all work performed on these transactions will be finalized. The following example contains an excerpt that shows the use of the commit method.

. . . // commit transaction try {

pub.commit(); } catch (BrokerException ex) { System.out.println ("Error on commit" +ex); return; } }

. . .

Aborting a Transaction

Use the abort method to end an open transaction, or use the abortAll method to end a given list of open transactions. These methods will discard all work previously performed and will invalidate the transaction(s).

The following example contains an excerpt that shows the use of the abort method.

. . . // abort transaction try {

pub.abort(); } catch (BrokerException ex) { System.out.println ("FAIL abort_publish:Error on transactional abort" +ex); return; }

. . .

Destroying the Transactional Client

Use the destroy method to destroy a transactional client. When a transactional client is destroyed, its event queue and all other client state information will also be destroyed. The following example contains an excerpt that shows the use of the destroy method.

. . . //destroy the transactional client try { pub.destroy(); } catch (BrokerException ex) { System.out.println ("Failed to destroy pub client\n" + ex); System.exit(1); } . . .



Creating a Transactional Client

To work purely in a transactional environment interacting with transactional methods, only the BrokerTransactionalClient object is required. The following example shows how to create a BrokerTransactionalClient object. Note that the following example also applies to reconnectTransactionalClient() method.

public void connect() {

BrokerTransactionalClient pub, sub;

/* Create publisher */ try { pub = BrokerTransactionalClient.newOrReconnectTransactionalClient

(broker_host, broker_name,pubid, client_group_p, "TxTest-Pub", null);

} catch (BrokerException ex) { System.out.println ("Failed to create pub client\n" + ex); System.exit(1);

}

/* Create subscriber */ try { sub = BrokerTransactionalClient.newOrReconnectTransactionalClient (broker_host, broker_name, subid, client_group_s, "TxTest-Sub",

null); } catch (BrokerException ex) { System.out.println ("Failed to create pub client\n" + ex); System.exit(1); }




8 Publishing and Delivering Events

Publishing Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132

Delivering Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 133



Publishing Events

When your client application publishes an event, the Broker places it in the event queue of each BrokerClient that has subscribed to that event type.

Note: Event types are defined with Software AG Designer, described in the Software AG Designer Online Help. Please note that events are known as document types in Designer.

In order for your application to be able to publish an event, it must first create a BrokerClient, as described on “Creating and Destroying Broker Clients” on page 40. Your application can then use the BrokerClient to create an event, as described on “Creating Events” on page 70. After setting the event fields, as described on “Setting Sequence Fields” on page 76, your application is ready to publish the event.

Limits on Publication

The client group to which the BrokerClient belongs defines the event types the BrokerClient can publish. See “Client Groups” on page 39 for more information. The following example contains an excerpt from the publish1.java sample application that shows the use of the BrokerClient.canPublish method to check for event publication permission. This method simply requires an event type name.

. . . BrokerClient c; boolean can_publish; . . . /* Check publish permission */ try {

can_publish = c.canPublish("Sample::SimpleEvent"); } catch (BrokerException ex) {

System.out.println("Error on check for can publish\n"+ex); return;

} if (can_publish == false) {

System.out.println("Cannot publish event"); System.out.println("Sample::SimpleEvent."); System.out.println("Make sure it is loaded in the broker and"); System.out.println("permission is given to publish it in the"); System.out.println(client_group + " client group."); return;

} . . .

You can also use the BrokerClient.getCanPublishNames method to obtain the names of all the event types which a Broker client can publish.



Publishing an Event

After initializing the necessary event fields, your application can publish an event by calling the BrokerClient.publish method. The following example contains an excerpt from the publish1.java sample application that shows the use of the BrokerClient.publishEvent method. This method accepts a BrokerEvent.

. . . BrokerClient c; BrokerEvent e; . . . try {


System.out.println("Error on publish\n"+ex); return;

} . . .


Your application can publish several events with one call to the BrokerClient.publish method that accepts an array of BrokerEvent objects. The following example contains an excerpt that shows the use of this method, which accepts a BrokerEvent array.

. . . BrokerClient c; BrokerEvent e[5]; . . . /* Create and initialize the event array */ . . . try {


System.out.println("Error on publish\n"+ex); return;

} . . .

The BrokerClient.publishWithAck method can be used by your Broker client to publish one or more events while, at the same time, acknowledging the receipt of one or more events. For more information on event acknowledgement, see “Using Sequence Numbers” on page 145.

Delivering Events

In addition to publishing events to potentially many Broker clients, the webMethods Broker system also allows your application to deliver an event to a single Broker client, through the Broker. In order to deliver an event to a specific Broker client, your application must have the client identifier of that client.



Note: The recipient of a delivered event does not have to register a subscription for the event type being delivered. The recipient only needs to be permitted to receive the delivered event type, as specified by the client group of the receiving Broker client.

Obtaining the Client Identifier

You can either hard code the client identifier of the recipient, if it is well known, or you can extract the identifier from a event that you have received from the Broker client as shown in the following example.

. . . BrokerEvent e; String client_id; . . . try {

client_id = e.getStringField("_env.pubId"); } catch (BrokerException ex) {

System.out.println("Error on getting destination ID\n"+ex); return;

} . . .

Delivering an Event

The following example shows the use of the BrokerClient.deliver method to deliver a single event. This method accepts these parameters:

A string containing the destination identifier (client identifier of the recipient).

The BrokerEvent to be delivered.

Note: Delivering an event to a Broker client that no longer exists will not return an error.

. . . BrokerClient c; BrokerEvent e, event; String dest_id; . . . /* create a client */ . . . /* open any subscriptions */ . . . /* receive an event */ . . . /* create the event to be sent and set the event fields */ . . . /* obtain the client id of the recipient from the received event */ try {

dest_id = event.getStringField("_env.pubId"); } catch (BrokerException ex) {




} /* Deliver the event to the recipient */ try {

c.deliver( dest_id, e); } catch (BrokerException ex) {

System.out.println("Error on delivering event\n"+ex); return;

} . . .

Delivering Multiple Events

The following example shows the use of the BrokerClient.deliver method to deliver multiple events. This method accepts these parameters:


The array of events to be delivered.

Delivering multiple events

. . . BrokerClient c; BrokerEvent e[5]; BrokerEvent event; String dest_id; ... /* create the events to be sent and set their event fields */ . . . /* obtain the client id of the recipient */ try {

dest_id = event.getStringField("_env.pubId"); } catch (BrokerException ex) {


} /* Deliver the event to the recipient */ try {

c.deliver( dest_id, e); } catch (BrokerException ex) {

System.out.println("Error on delivering events\n"+ex); return;

} . . .

The BrokerClient.deliverWithAck method can be used by your Broker client to deliver one or more events while, at the same time, acknowledging the receipt of one or more events. For more information on event acknowledgement, see “Using Sequence Numbers” on page 145.




9 Handling Errors

Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 138

BrokerExceptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 138

Setting the System Diagnostic Level . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 139


9 Handling Errors

Overview

This chapter describes how to handle exceptions thrown by webMethods Broker API methods. Reading this chapter will help you understand:

How to catch exceptions.

How to obtain error codes.

How to set the webMethods Broker system diagnostic level.

How to display the descriptive text associated with an exception.

BrokerExceptions

Many of the webMethods Broker API methods are designed to throw a BrokerException when an error occurs. The BrokerException class is the base class for all the exceptions that can be thrown by the webMethods Broker API. For a list of all of the possible exceptions, see “API Exceptions” on page 413.

Catching Exceptions

The example below shows how to catch an exception thrown by an webMethods Broker API method invocation. If an exception is thrown, this example code will print out the contents of the exception and return.

. . . BrokerClient c;

. . . /* Create a client */ try {


} catch (BrokerException ex) { System.out.println("Error on create client\n"+ex);

return; }

. . .

Determining the Exception Type

You have two options for determining the exact type of exception that has been thrown.

1 You can develop your code to catch the specific types of exceptions that you expect, as shown in the following example:




9 Handling Errors


} catch (BrokerClientExistsException ex) { System.out.println("Can’t create client, already exists\n"); return;

} catch (BrokerNotRunningException ex) { System.out.println("Can’t create client, Broker not running\n");

return; . . .

2 You can catch the BrokerException super-class and use the instanceof operator to determine which type of exception you have caught, as shown in the following example:




} catch (BrokerException ex) { If(ex instanceof BrokerClientExistsException) {

System.out.println("Can’t create client, already exists\n"); return;

} else if(ex instanceof BrokerNotRunningException) { System.out.println("Can’t create client, Broker not running\n");

return; . . .

} . . .

Getting an Exception Description

You can use the BrokerException.toString or BrokerException.toCompleteString methods to obtain a descriptive message from BrokerException. The BrokerException.toString method returns a brief message; the BrokerException.toCompleteString method returns a more detailed description.

Setting the System Diagnostic Level

The BrokerException class provides two static methods you can use to query and set the level of error reporting that the webMethods Broker system will present as standard output for your application.

Use the BrokerException.setDiagnostics method to set the level or error reporting.

Use the BrokerException.getDiagnostics method to query the current diagnostic level.

Each of these methods uses the following diagnostic levels:


9 Handling Errors

Diagnostic Level Description

0 No error output will be produced. Use this setting for deployed applications.

1 Produces error output for major errors only. This is the default setting

2 Produces all error output for all public methods. Use this setting when debugging an application.


10 Using BrokerDate Objects

Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 142

Date and Time Representation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 142

BrokerDate Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 142



Overview

This chapter describes the webMethods Broker API for representing and manipulating date and time representations. Reading this chapter should help you understand how to create, set, and query a BrokerDate object.

Date and Time Representation

The webMethods Broker API uses the BrokerDate class to provide a simplified date and time representation for your applications. The BrokerDate class contains the following data members:

BrokerDate Methods

When you construct a new BrokerDate object and specify a date and time, the is_date_and_time member is set to true. If you construct an empty BrokerDate, the is_date_and_time member is set to false by default.

Other BrokerDate methods include:

Data Member Description

int year Year value. Must be less than 4096.

int month Month value.

int day Day value.

int hour Hour value.

int min Minute value.

int sec Second value.

int msec Millisecond value.

boolean is_date_and_time

Set to true if both date and time are represented. Set to false if only a date is represented.

Method Description

clear Clears the entire contents of this BrokerDate.

clearTime Clears only the hour, minute, second, and millisecond.

compareTo Determines if one BrokerDate greater than, equal to, or less than another BrokerDate.

equals Determines if one BrokerDate is equal to another.

getJavaCalendar Converts a BrokerDate to a Java Calendar object.



getJavaDate Converts a BrokerDate to a Java Date object.

parseDate Creates a BrokerDate and sets it to the date and time contained in the specified String.

parseLocalizedDate Creates a BrokerDate and sets it to the date and time contained in the specified String.

setDate Sets the year, month, and day. Year must be < 4096.

setDateTime Sets the date and time.

setJavaCalendar Sets a BrokerDate from a Java Calendar object.

setJavaDate Sets a BrokerDate from a Java Date object.

setTime Set only the hour, minute, second, and millisecond.

toLocalizedString Returns a string representation of a BrokerDate, using a specified Locale.

toString Returns a string representation of a BrokerDate using the java.util.Locale.US.

Method Description




11 Using Sequence Numbers

Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 146

Sequence Numbers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 146

Publisher Sequence Numbers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 146

Receipt Sequence Numbers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 147



Overview

This chapter describes how to use event sequence numbers to ensure reliable event delivery. Reading this chapter should help you understand:

How to use publish sequence numbers.

How to use receipt sequence numbers.

Sequence Numbers

Sequence numbers in the webMethods Broker system are designed to ensure that events are delivered reliably. The use of sequence numbers is optional, but is recommended if your application requires reliable delivery of events and is capable of storing and tracking these numbers.

Sequence numbers can be used between a publishing application and the Broker or between the Broker and a receiving application. Here are some common characteristics of both publish and receipt sequence numbers:

Sequence numbers are 64-bit unsigned integers that contain non-zero values.

Sequence numbers are always incremented and are assumed to never wrap back to 1.

Publisher Sequence Numbers

You do not need to use publisher sequence numbers if your only concern is whether or not a published or delivered event gets to the Broker. If your application's publish or deliver method returns successfully, the event was transmitted to the Broker. If the publish or deliver method fails, you can simply send the event again.

When you re-send an event, there is a small chance a duplicate event will be presented to the Broker. The Broker might successfully receive a published event, but then encounter some error that prevents it from notifying your application. Avoiding this situation can be important if your application is dealing with financial transactions, for example.

When your application uses publisher sequence numbers, it allows the Broker to recognize and discard duplicate events. When used properly, this eliminates the window of opportunity for the presentation of duplicate events to the Broker.

Note: Starting with version 6.1, the use of publisher-assigned sequence numbers has been deprecated for use with transactional clients (BrokerTransactionalClient). However, their use with non-transactional clients (BrokerClient) will continue to be supported.



Using Publisher Sequence Numbers

When the Broker receives an event with a sequence number that has not been set or is set to zero, it assumes that event sequence numbering rules are not to be applied to the event. If your application does not want to use publish sequence numbers, it simply should not set them or set them to zero.

Your application can set a non-zero publish sequence number for an event by calling theBrokerEvent.setPublishSequenceNumber prior to publishing or delivering the event. The BrokerClient.deliverAckReplyEvent and BrokerClient.deliverNullReplyEvent methods allow you to specify a publish sequence number directly.

When the event is published or delivered, the Broker will discard the event if the sequence number is less than or equal to the highest sequence number received from that Broker client so far.

Note: To ensure that events are not discarded, publishing applications should use increasing sequence numbers. The sequence number values, however, can be incremented by a value greater than one.

Maintaining Publish Sequence Number State

To make the most of publisher sequence numbers, publishing applications should store, in some reliable way, the sequence numbers of successfully transmitted events. This will allow them to continue publishing where they left off if they should terminate unexpectedly and need to be restarted.

Your application can use the BrokerClient.getLastPublishSequenceNumber method to determine the highest sequence number that it has used so far.

Your application can obtain the current setting on an event's sequence number by calling the BrokerEvent.getPublishSequenceNumber method.

Receipt Sequence Numbers

Receipt sequence numbers can be used to prevent the Broker from presenting duplicate events to your application's BrokerClient when it retrieves the next event. The Broker always sets sequence numbers on the events it presents to receiving clients. If your receiving client acknowledges an event's sequence number, the Broker will not present that event again.

Note: Volatile events are not assigned sequence numbers by the Broker, so they cannot be specifically acknowledged. Volatile events are deleted from the client's event queue as soon as they are retrieved by a Broker client.



Default Acknowledgment

The following methods will automatically acknowledge all previously retrieved events for your receiving Broker client, effectively ignoring sequence numbers:

BrokerClient.getEvent

BrokerClient.getEvents

This default behavior avoids the loss of events from the client's queue in cases where your application crashes while processing an event, because the event is not acknowledged until the next time your Broker client requests an event. The next time your Broker client requests an event, the Broker will assume the last retrieved event has already been processed.

Your Broker client can acknowledge the received event by either asking for another event, using the same get-event method, or by explicitly calling BrokerClient.acknowledge. A Broker client that is implicitly acknowledging events would normally call BrokerClient.acknowledge only if it is planning to exit and wants to acknowledge all previously retrieved events without actually receiving any more events.

Note: Before exiting, Broker clients with an explicit-destroy life cycle that are using BrokerClient.getEvent or BrokerClient.getEvents with implicit acknowledgment should explicitly acknowledge the receipt sequence number of the last event received using either BrokerClient.acknowledge or BrokerClient.acknowledgeThrough. Failure to do so will result in the last event being received again the next time you connect the Broker client.

Default Acknowledgment With Callbacks

Your Broker client has much less flexibility in acknowledging events when it registers callback objects to process events, as described in “Using the Callback Model” on page 59. All callback event handling methods must either return true or false. If true is returned, the event will automatically be acknowledged. If false is returned, the event is assumed to have not been successfully handled and, therefore, it is not acknowledged.

Important! If an event meets the criteria for more than one callback object and any one of the callback event handling methods returns false, that event will not be acknowledged.

Explicitly Acknowledging Events

By explicitly acknowledging events, your application retains a greater degree of control over what events the Broker will maintain.

Your Broker client can use the BrokerClient.getEvents method to obtain one or more events from the Broker while simultaneously acknowledging events through a specified sequence number. If the sequence number is set to -1, no acknowledgment is sent and you can then use one of the following two methods to explicitly acknowledge the events you choose.



Your Broker client can use the BrokerClient.acknowledge method to acknowledge the receipt of a single event with the specified sequence number. If a sequence number of zero is specified, all previously unacknowledged events will be acknowledged.

Your Broker client can use the BrokerClient.acknowledgeThrough method to acknowledge the receipt of all events up to and including the event with the sequence number specified. If a sequence number of zero is specified, all previously unacknowledged events will be acknowledged.

The BrokerClient.deliverWithAck method can be used by your Broker client to deliver one or more events while, at the same time, acknowledging the receipt of one or more events.

The BrokerClient.publishWithAck method can be used by your Broker client to publish one or more events while, at the same time, acknowledging the receipt of one or more events.

Maintaining Receipt Sequence Number State

To make the most of explicitly acknowledging receipt sequence numbers, your receiving applications should store, in some reliable way, the receipt sequence numbers of successfully processed events. This will allow your applications to continue receiving events where they left off if they should terminate and need to be restarted.

You can use the BrokerEvent.getReceiptSequenceNumber method to obtain the receipt sequence number from a received event.

Other Considerations

The Broker guarantees that events from a single publishing client cannot be processed out of order. This has important implications when more than one Broker client is sharing the same event queue because the Broker will not return an event to Broker client which is incapable of acknowledging the event.

The table below shows an example client event queue containing event received from three different publishing clients; Client A, Client B, and Client C.

Consider these steps:

Publishing Client Event Queue Position

Client A 1

Client B 2

Client A 3

Client C 4

Client B 5

Client C 6



1 Broker client X receives the event from queue position 1 without acknowledging the event.

2 Broker client Y receives the event from queue position 2 without acknowledging the event.

3 Broker client Y then asks for another event and is given the event from queue position 4.

Because the last event from publishing Broker client A has not yet been acknowledged, the next event in the queue from Broker client A cannot be given to a different receiving Broker client.

By enforcing these acknowledgment rules, the Broker allows you to write client applications that process events from a single queue across multiple threads of control.


12 Managing Event Types

Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 152

Event Type Definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 152

Event Type Definition Cache . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 155

Infosets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 156



Overview

This chapter describes the webMethods Broker objects and methods for managing event types. Reading this chapter will help you understand:

The information contained in an event type definition.

How to obtain event type information from a Broker or from a received event.

How to determine which Broker is managing an event type and the territory to which that Broker belongs.

How event type definitions are cached and how to manage the cache.

The information contained in an infoset.

How to access infosets.

Event Type Definitions

The BrokerTypeDef class contains important information about a particular event type, including the event's fields and their data type. Both the Broker and the webMethods Broker API use event type definitions to verify that an event's fields are set with the correct data types. Event type definitions are also used if you call the BrokerEvent.validate method to validate an event that your application might have received or created.

Several methods are provided to enable your Broker client to obtain event type definitions. After you have obtained an event type definition, you can obtain information on all of the event's fields and their associated data types. Your Broker client might need to obtain event type information to be able to dynamically handle event types whose format has changed since the client application was compiled.

Obtaining Event Type Names

You can obtain an event type definition from an event or using an event type name.

Use the BrokerClient.getEventTypeNames method to obtain the names of all the event types managed by the Broker to which your Broker client is connected.

Use the BrokerTypeDef.getTypeName method to obtain the fully qualified event type name from an event type definition.

Use the BrokerClient.getScopeNames method to obtain the names of all the event types within a particular scope.

Use the BrokerTypeDef.getBaseTypeName method to obtain the unqualified event type name from an event type definition.

Use the BrokerTypeDef.getScopeTypeName method to obtain the scope name from an event type definition.



Obtaining Event Type Definitions

Use the BrokerClient.getEventTypeDef method to obtain a single event type definition, given an event type name.

Use the BrokerClient.getEventTypeDefs method to obtain multiple event type definitions using a list of event type names. You can obtain a list of event type names by using the BrokerClient.getEventTypeNames method.

Use the BrokerEvent.getTypeDef method to obtain the a single event type definition for an event.

Use the BrokerClient.getCanPublishTypeDefs method to obtain all the event type definitions which a particular Broker client has permission to publish.

Use the BrokerClient.getCanSubscribeTypeDefs method to obtain all the event type definitions to which a particular Broker client has permission to subscribe.

Obtaining Event Field Information

Your client application can use an event type definition to obtain information about the event's fields and their associated types.

Use the BrokerTypeDef.getFieldNames method to obtain a list of all the field names from a event type definition.

Use the BrokerTypeDef.getFieldType method to obtain the type of a specific event field from a event type definition.

Use the BrokerTypeDef.getFieldDef method to obtain the definition of a specific event field.

Obtaining Event Type Descriptions

Use the BrokerTypeDef.getDescription method to obtain an event type definition's description.

Obtaining Storage Type Property

An event type's storage type property specifies the how events of its type will be stored by the Broker.

Storage Type Description

STORAGE_GUARANTEED A two-phase commit process is used to store incoming events on the Broker. This offers the lowest performance, but very little risk of losing events if a hardware, software, or network failure occurs



Use the BrokerTypeDef.getStorageType method to obtain the storage type for an event type.

Client groups have two storage modes; guaranteed and volatile. A client group's storage mode represents the highest storage mode allowed for any events being put into the event queue of a client belonging to that group. With one exception, the Broker will put events into a client's queue using the lesser of the client group's storage mode and the event type's storage mode, as shown in the table below.

Obtaining the Time-to-live Property

An event type's time-to-live property specifies how long an event will available after being published before it expires and is deleted. Use the BrokerTypeDef.getTimeToLive method to obtain an event type's time-to-live. A time-to-live value of zero means events of that type will never expire.

Obtaining Type Definitions as Strings

You can use the BrokerTypeDef.toString method to obtain a string representation of an event type definition.

Obtaining Broker Information

Each Broker to which a Broker client can connect manages its own set of event type definitions. It can be useful for your client application to obtain information about the Broker that is managing a particular event type definition.

Use the BrokerTypeDef.getBrokerHost method to obtain host name where the Broker managing a particular event type definition is executing.

Use the BrokerTypeDef.getBrokerName method to obtain the name of the Broker that is managing a particular event type definition.

STORAGE_VOLATILE Local memory is used to store incoming events on the Broker. This offers higher performance along with a greater risk of losing events if a hardware, software, or network failure occurs.

If the Client Group Storage Mode is...

And the Event Type Storage Mode is...

Broker will put events into a client's queue using...

Volatile Volatile Volatile

Volatile Guaranteed Volatile

Guaranteed Volatile Volatile

Guaranteed Guaranteed Guaranteed

Storage Type Description



Use the BrokerTypeDef.getBrokerPort method to obtain IP port number of the Broker that is managing a particular event type definition.

Broker Territory and Broker-to-Broker Communication

webMethods Broker allows two or more Broker Servers to share information about their event type definitions and client groups. This enables communication between Broker clients connected to different Brokers. In order to share information, Brokers join a territory. All Brokers within the same territory have knowledge of one another's event type definitions and client groups. For more information on this feature, see Administering webMethods Broker.

Use the BrokerTypeDef.getTerritoryName method to obtain the territory name of the Broker that is managing this event type definition.

Event Type Definition Cache

The webMethods Broker API keeps a copy of each event type definition used by your application in an event type cache. The cache improves the performance of the event field type checking process because the Broker managing the event type does not have to be contacted each time the event type definition is accessed.

The operation of the event type definition cache is usually transparent to your application. Problems can arise if Software AG Designer is used to alter a Broker's event definitions while your application is executing. In these cases, the locally cached event type definitions will no longer be synchronized with the Broker's type definitions. You can use the static methods offered by the BrokerTypeCache class to control the local event type definition cache.

Notification of Event Type Definition Changes

If your application needs to know when a Broker's event type definitions have changed, it can subscribe to the event type Adapter::refresh. Whenever this event type is received, your application will know the local event type definition cache needs to be synchronized with the Broker.

Use the BrokerTypeCache.flushCache method to cause the cache contents to be refreshed. This is an advanced method and its use is not required in most situations.

Locking the Type Definition Cache

Multi-threaded applications can run into problems if one thread is accessing event type definition information and another thread calls the BrokerTypeCache.flushCache method. In these situations, threads that need to access the type definition cache should lock the cache before using any of the following methods:

BrokerClient.getEventTypeDef



BrokerClient.getEventTypeNames

BrokerTypeDef.getBrokerHost

BrokerTypeDef.getBrokerName

BrokerTypeDef.getBrokerPort

BrokerTypeDef.getTypeName

BrokerTypeDef.getFieldNames

BrokerTypeDef.getFieldType

Use the BrokerTypeCache.lockCache method to lock the local type definition cache and prevent it from being altered or flushed.

After a thread has finished accessing event type definition information, it should unlock the cache using the BrokerTypeCache.unlockCache method.

Infosets

Each event type has a set of one or more infosets that describe configuration information for the event type.

An event type's public infoset defines the semantics of the event. In particular, the public infoset defines the event type of a reply that can be expected for an event.

Note: While infosets are neither events nor event types, the methods for obtaining them return the infoset as a BrokerEvent for convenience.

Use the BrokerClient.getEventTypeNames method to obtain the names of all the infosets defined for a particular event type name.

Use the BrokerClient.getEventTypeInfoset method to obtain a single infoset, given an event type name and the infoset name.

Use the BrokerClient.getEventTypeInfosetNames method to obtain a list of infosets, given an event type name and a list of infoset names.


13 Using Event Filters

Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 158

Filter Strings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 158

Using Filters with Subscriptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 169

Using BrokerFilters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 169



Overview

This chapter describes the webMethods Broker event filtering facilities, which allow both the Broker and your Broker clients to quickly determine whether an event's contents meet specified criteria. Reading this chapter will help you understand:

How to specify a filter string.

How to use a filter string with an event subscription.

How to use a BrokerFilter within your client application, to match events with filter criteria.

Filter Strings

A filter string specifies criteria for the contents of an event. When you specify a filter string with an event subscription, the Broker uses the filter string to determine which events match your criteria. The Broker will place in your Broker client's event queue just the events that match the filter string.

Filter strings can do any combination of the following:

Refer to the content of event fields by using field identifiers.

Compare event field contents against constants or computed values.

Combine event field comparisons using the boolean operators AND, OR, and NOT.

Perform arithmetic operations on event fields and constants.

Contain regular expressions.

Contain string and arithmetic constants.

Contain a hint that specifies how events should be processed.

Specifying Filter Strings

Consider an event that contains a person's age and the state in which they live. The first event field might have the name age and the second might have the field name state. The following filter string would match only those events whose age field was greater than 65 and whose state field was equal to "FL".

age > 65 and state = "FL"

In this example filter string, age and state represent event fields. This filter also contains an arithmetic constant 65 and a string constant "FL". The boolean operator and is used to combine the field criterion for age and state.

Other example filter specifications:



debt > salary*0.50 packaging = "portable" and price > 5000 answer = 'Y' or answer = 'y' (answer = 'Y') or (answer = 'Y')

Filter string can also make use of the filter functions described on “Filter Functions” on page 164.

Locale Considerations

The current locale for your application is defined by your operating system, and allows your application to adapt itself to different languages, character sets, time zones, date formats, and monetary conventions.

You can specify a specific locale to be used with your filter at the time you construct a BrokerFilter object.

If you do not specify a particular locale, your filter string is handled using your current locale setting.

Important! The Broker uses a filter string to determine which events match your criteria and that evaluation occurs using the Broker's locale, not your application's locale. This might cause unexpected or unintended event filtering.

The java.text.Collator class is used when comparing strings to provide locale sensitivity. However, this might vary depending on the Java implementation you are using.

Filter Rules

A filter string must adhere to these rules:

1 Field names can be fully qualified, such as

struct_field.seq_field[2]

2 A character constant is a single character surrounded by single quotes, such as 'A'.

3 A string constant is zero or more characters surrounded by double quotes, such as "account".

4 If a character or string constant contains a single or double quote, precede the quote with a backslash. For example: "\"

5 Parentheses can be used to control the order of operator precedence, described in “Operator Precedence” on page 162.

6 A division operation must not result in divide by zero.

Field Names

When referring to a structure or sequence field within a filter string, you can use a fully qualified field name. Consider the event type definition shown in the following example.



Sample::StructEvent { string count; int scores[]; struct sample_struct {

BrokerDate sample_date; int sample_array [];

} }

To refer the third integer in the sequence field scores, you would use the field name scores[2] in your filter string.

To refer to the field sample_date within the struct field sample_struct, you would use the field name sample_struct.sample_date in your filter string.

To refer to the first integer in the sequence field sample_array, you would use the field name sample_struct.sample_array[0] in your filter string.

Filter Operators

The following tables contain the various operators that you can use to create filters.

Logical Filter Operators

Comparison Filter Operators

Operator Description

! not

Not

&& and

And

|| or

Or


< Less than

<= Less than or equal to

> Greater than

>= Greater than or equal to

= Equal to

== Equal to

!= Not equal to



Arithmetic Filter Operators

Note: Implicit type conversion occurs when operands in an arithmetic operation have different types. The operands are converted to a larger value before the comparison occurs. Type char is considered numeric, but boolean is not.

Bitwise Operators

String Operators


- Unary minus

* Multiplication

/ Division

% Modulus Division

- Subtraction

+ Addition


~ Bitwise compliment

<< Shift left

>> Shift right

& Logical and

| Logical or

^ Logical exclusive or


+ Concatenation

< Less than

<= Less than or equal to

> Greater than

>= Greater than or equal to

= Equal to

== Equal to

!= Not equal to



Operator Precedence

The following table describes the precedence and order of evaluation of all of the filter operators. Operators appearing on the same line have the same precedence.

Operator Description Order of evaluation

() Function left to right

not

!

~

-

logical not

logical not

bitwise not

minus

right to left

*

/

%

multiplication

division

modulus division

left to right

-

+

subtract

add

left to right

<<

>>

left shift

right shift

left to right

<

<=

>

>=

less that

less that or equal to

greater than

greater than or equal to

left to right

=

==

!=

equal

equal

not equal

left to right

& bitwise and left to right

^ bitwise exclusive or left to right

| bitwise or left to right

and

&&

logical and left to right

or

||

logical or left to right



Using Regular Expressions

Regular expressions allow you to specify a complex pattern that is to be matched with an input string. The regexpMatch filter function accepts a regular expression as an argument.

A regular expression is made up of one or more basic components called atoms. An atom is used to match a single character in the input string or it can represent multiple occurrences of one or more characters.

If each atom in a regular expression matches a corresponding element in the input string, the expression is said to match the input string.

Using Hints

You can include a hint in you subscription by adding a string with the following format.

"{hint: HintName=Value}"

The table below shows the supported HintNames and their associated values.

Characters Matches

. Any single character in the input string.

^ A null string at the start of the input string.

$ A null string at the end of the input string.

\x The character x. A special character that you want to match in the input string can be escaped in this manner, such as \^ or \$.

[chars] Any single character from chars.

Specifying [a-z] will match any input string containing all lowercase characters. Specifying [0-9a-fA-F] will match any input string containing hexadecimal digits.

If a ] character appears as the first characters in chars, it will be treated literally instead of as a terminator.

[^chars] Any single character that is not contained in chars.

(regexp) Any input string that matches regexp. Parentheses can be used to create complex regular expressions.

* A sequence of 0 or more of the preceding atom.

+ A sequence of 1 or more of the preceding atom.

? Either a null string or the preceding atom.

regexp1|regexp2 Anything that matches either regexp1 or regexp2. Note that the | delimiter cannot be preceded by or followed by a blank space.



Filter Functions

Several functions are provided by the webMethods Broker API that you can use within filter strings. These functions allow you to perform complex string operations, regular expression matches, and string to numeric conversions on event field values. Some examples of the use of functions within filter strings are shown below.

charAt(my_string_field,5) = charAt("StringConstant",my_i startsWith(toUpperCase(myfie toString(my_long_field) = "4 toLong(my_string_field) = 42

charAt

char charAt( string s, int index)

Returns the character with the specified index from the event field with the name specified by s.

contains

boolean contains( string s, string substr)

HintName and Value Description

IncludeDeliver=true

Causes events that are delivered to a Broker client to match a subscription, along with events that are published.

LocalOnly=true In a multi-Broker environment, this causes a subscription to match only those events that originate from the Broker to which this Broker client is connected. Events originating from a different Broker are excluded from the subscription.

DeadLetterOnly=true

Creates a subscription to deadletters. Deadletters are events to which the local Broker has no registered subscriptions. For information about creating deadletters, see “Detecting Deadletters” on page 104.

s The name of an event field containing a string.

index The index of the character within the string field that is to be returned. This index is zero-based, so the first character has an index of 0.


substr The string that is being searched for.



Returns true if the string substr occurs within the event field with the name specified by s, otherwise false is returned.

date

date date( int year, int month, int day)

Creates a date value with the specified day, month, and year.

date

date date( int year, int month, int day, int hour, int minute, int second, int millisecond)

Creates a date value with the specified millisecond, second, minute, hour, day, month, and year.

endsWith

boolean endsWith( string s1, string s2)

year The year.

month The month.

day The day.

year The year.

month The month.

day The day.

hour The hour.

minute The minute.

second The second.

millisecond The millisecond.

s1 The name of an event field containing a string.

s2 The string being searched for.



Returns true if the event field with the name specified by s ends with the string s2, otherwise false is returned.

regexpMatch

boolean regexpMatch( string s, string regexp)

Returns true if the event field with the name specified by s matches the UNIX regular expression regexp, otherwise false is returned.

Important! This function does not support the X/Open regular expression specification. Unicode characters and strings are also not supported by this function.

startsWith

boolean startsWith( string s1, string s2)

Returns true if the event field with the name specified by s begins with the string s2, otherwise false is returned.

substring

string substring( string s, int index1, int index2)

Returns a substring from the event field with the name specified by s, beginning with the character at index1 and ending at the character at index2.


regexp A string containing a UNIX regular expression.

s1 The name of an event field containing a string.

s2 The string being searched for.

s The event field from which the substring is to be extracted.

index1 The index of the character within the string field where extraction is to begin. This index is zero-based, so the first character has an index of 0.

index2 The index of the character within the string field where extraction is to end. This index is exclusive.



toDouble

double toDouble( <type> field)

Returns a double containing the event field field. Any supported field type, except for dates, structures, and sequences, can be converted.

Note: The locale-specific radix character will be recognized when converting a floating point number.

toInt

int toInt( <type> field)

Returns an int containing the event field field. Any supported field type, except for dates, structures, and sequences, can be converted.

toLong

long toLong( <type> field)

Returns a long containing the event field field. Any supported field type, except for dates, structures, and sequences, can be converted.

toLowerCase

string toLowerCase( string s)

Returns a copy of the string from the event field with the name specified by s, but with all uppercase characters converted to lowercase. Any non-alphabetic or lowercase characters in s are returned unaltered.

Note: This function supports locale sensitivity to the extent possible on your particular platform.

field The name of an event field to be converted.






toString

string toString( <type> field)

Returns a string containing the event field field, converted to a string. Any supported field type, except for structures and sequences, can be converted.

Note: The locale-specific radix character will be used when converting a floating point type.

toUpperCase

char toUpperCase( string s, int index)

Returns a copy of the string from the event field with the name specified by s, but with all lowercase characters converted to uppercase. Any non-alphabetic or uppercase characters in s are returned unaltered.


toUpperCase

char toUpperCase( string s)

Returns a single character from the event field with the name specified by s, converted to uppercase. If the specified character is non-alphabetic or is already uppercase, it is returned unaltered.




index The index of the character within the string field that is to be returned. This index is zero-based, so the first character has an index of 0.




Using Filters with Subscriptions

When you subscribe to a particular event type using the BrokerClient.newSubscription method, you can specify an optional event filter string. The filter string you specify will be used by the Broker when determining if an event should be placed in your Broker client's event queue. Only those event types for which your Broker client has subscribed that also match the filter specification will actually be placed into your Broker client's event queue. The following example shows how to create an event filter string and use it with an event subscription.

BrokerClient c; String filter_string; . . . filter_string = "(A<B) and ((C+12) > (D*3))"; . . . /* Make a subscription */ try {

c.newSubscription("Sample::SimpleEvent",filter_string); } catch (BrokerException ex) {


} . . .

Using BrokerFilters

You client application can create a BrokerFilter using the BrokerFilter constructor. A BrokerFilter can be used locally by the client application, in conjunction with the BrokerFilter.match method, to determine whether a particular event type matches the filter.

When creating a BrokerFilter, you must specify an event type name and a filter string. You can then use the BrokerFilter.match method to check any events that your client application might receive.

The following example shows a code excerpt that creates three filters for use by a client application. The BrokerFilter.match method is then used to determine whether the event matches each filter's criteria.

. . . BrokerClient my_client; BrokerEvent e; . . . special = new BrokerFilter(my_client,"Type1",

"(A<B) && ((C+12) >(D*3))"); type1 =new BrokerFilter(my_client, "Type1", null); type2 = new BrokerFilter(my_client,"Type2", null);

try {

e = c.getEvent(-1); } catch (BrokerException ex) {

System.out.println("Error on getting event\n"+ex); return;



} if (special.match(e)) {

/* A special case of Type1 events that requires special processing */ . . . } else if (type1.match(e)) {

/*A Type1 event */ . . .

} else if (type2.match(e)) { /* A Type2 event */ . . .

} . . .

To do this same processing without filters, your code would look like that shown in the following example.

. . . BrokerClient my_client; BrokerEvent e; String name; Int a, b, c, d; . . . try {

e = c.getEvent(-1); } catch (BrokerException ex) {

System.out.println("Error on getting event\n"+ex); return;

}

name = e.getTypeName(); a = e.getIntegerField("A"); b = e.getIntegerField("B"); c = e.getIntegerField("C"); d = e.getIntegerField("D"); if( (name.equals(“Type1”) && (a<b) && ((c+12) >(d*3)) ) {

/* A special case of Type1 events that requires special processing */ } else if (name.equals(“Type1”) {

/*A Type1 event */ } else if (name.equals(“Type1”) {

/*A Type2 event */ } . . .

Obtaining Filter Strings

You can use the BrokerFilter.getFilterString method to obtain the filter string associated with a Broker filter.

Obtaining Event Type Names

You can use the BrokerFilter.getEventTypeNamemethod to obtain the event type name associated with a Broker filter.



Converting Broker Filters to Strings

The BrokerFilter.toString method allows you to obtain a character string containing the contents of a Broker filter.




14 Load Balancing and Failover for Publish Operations

Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 174

Understanding Clustering . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 174

Using BrokerClusterPublisher . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 176

Broker Cluster Publisher Connection Notification . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 181

Broker Cluster Publisher Selection Notification . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 182

Obtaining BrokerClusterPublisher Status . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 185

Publishing and Delivering Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 185



Overview

This chapter describes the webMethods Broker Java API for implementing client-side load balancing and failover for publish operations. Reading this chapter will help you to understand:

How to create and destroy a BrokerClusterPublisher.

How to disconnect or reconnect a BrokerClusterPublisher

How to register and use a cluster publisher connection callback.

How to register and use a cluster publisher selection callback.

How to include or exclude a specific Broker from the cluster publisher operations.

How load-balancing is achieved in BrokerClusterPublisher based solution.

Understanding Clustering

When a publish/deliver operation is executed on a valid Broker client connection, it is targeted for the specific Broker to which it is connected. If that Broker is unavailable, the operation fails.

When setting up client-side load balancing and failover, one or more Brokers that share some commonality (in terms of shared metadata and point-to-point connectivity) are brought together by sharing a territory.

In a territory where the metadata is common, publishers and subscribers can be on any of the Brokers in the territory and work as though they are on the same Broker. BrokerClusterPublisher pools together Broker client connections to individual Brokers in a territory and executes publish/deliver operations on any available Broker client connection.

To execute cluster operations, a BrokerClusterPublisher employs one or more Broker client connections to Brokers in a given territory. For an operation to succeed on a Broker client in the cluster pool, the Broker to which it is connected must be part of the same territory during execution. If a Broker becomes unavailable or leaves the territory, it is removed from the cluster pool and is not used until it becomes available again.

BrokerClusterPublisher also provides a means for choosing a specific Broker client connection for executing an operation against the default selection based on a simple round robin algorithm. BrokerClusterPublisher provides means for monitoring the connection activity. For example, a Broker leaving or joining the territory or a Broker becoming unavailable or is stopped. It also provides a flexible way of excluding or including a specific Broker on the territory for cluster operations at any point of time during the operations. It also provides some basic capabilities to retrieve permission and statistical information.



BrokerClusterPublishers

BrokerClusterPublisher is a multi-threaded client side solution exposed via Broker Java API applicable only in a territory environment. A BrokerClusterPublisher solution creates two types of client connection; one for monitoring the territory change activity and the other for executing publish/deliver operations as described by the application properties.

Monitoring Territory Activity

BrokerClusterPublisher always maintains a Broker client connection belonging to the system-defined client group "eventLog" for monitoring purposes. This client is used to discover Brokers in a territory at connection time and to detect territory changes such as Brokers leaving or joining that territory. There can be only one such monitoring client for a given BrokerClusterPublisher solution in the territory at any point of time. This is also referred to as Cluster Monitor Client. Cluster Monitor subscribes to territory change activity events and acts on them when a change occurs. For example, when a Broker leaves the territory and a Broker client connection to that Broker in the Broker cluster publisher pool exists, the cluster monitor will initiate an operation to remove the Broker client connection to that Broker from the pool. Similarly when a Broker joins the territory, the cluster monitor will initiate an operation to create and add a Broker client connection to the newly joining Broker in to the Broker cluster publisher pool.

Executing Publish/Deliver Operations

The second type of client connection represents actual application Broker client connections. It is based on the application client group and connection parameters as specified at the creation time. For a territory with one or more Brokers, a BrokerClusterPublisher would create a Broker client connection to each of the Brokers on the territory. These are the clients that actually execute publish or deliver operations invoked on the BrokerClusterPublisher object. These Broker client connections are maintained in a cluster connection pool from which the BrokerClusterPublisher will choose a client to execute an operation. These clients are referred to as Broker cluster publishers.

Load Balancing

Load refers to operations that are executed on a BrokerClusterPublisher object which are typically publish event(s), deliver event(s), publishRequestAndWait or deliverRequestAndWait.

Publishers and Subscribers

When a number of publish or deliver operations are invoked on a BrokerClusterPublisher object, it executes them on one of the Broker client connections from its Broker cluster publisher pool. In this way, the load is distributed onto more than one Broker in the territory setup.



In the classical territory setup, a published event is propagated to other Brokers for subscribers' consumption no matter where the event was published. With this BrokerClusterPublisher feature, a event can be published to a given Broker for the consumption of subscribers on that local Broker only avoiding any event propagation to other Brokers. This introduces a new type of publish operation referred to as local publish, which is available only through BrokerClusterPublisher. This enhances the scope of load balancing as far as the event consumption is concerned. A number of local publish operations on the BrokerClusterPublisher with subscribers on each of the territory Brokers would constitute a true load balanced solution. Any change to the event type definition or client group properties is propagated to all the Brokers on the territory, ensuring the integrity of the metadata.

Even for a single subscriber/publisher publishing path in a territory, Broker has some advantages in a BrokerClusterPublisher based solution. When the Broker on which publish operation is being attempted becomes unavailable, BrokerClusterPublisher would automatically retry the operation on a different Broker from the Broker cluster publisher pool until it succeeds. After the event is published successfully, the territory nature will take care of forwarding the event to right Broker where the subscriber is connected.

Failover

BrokerClusterPublisher does not implement any specific functionality to achieve failover, rather it is an inherent property that is delivered with load balancing. When a publish operation is invoked on a BrokerClusterPublisher object, it is then executed on one of the Broker client connections from the Broker cluster publisher pool. If the Broker stops while executing the publish operation, BrokerClusterPublisher will automatically reissue the publish operation on a different Broker client connection in the Broker cluster publisher pool. BrokerClusterPublisher also reissues the operation when the Broker client used for execution represents a Broker that has left the territory.

Using BrokerClusterPublisher

Creating and Destroying BrokerClusterPublisher

BrokerClusterPublisher class has many conventional similarities with Broker client class. It has a constructor that uses parameters like Broker host, Broker name, client group name, client identifier and other application client properties as described by a BrokerConnectionDescriptor object. In addition, it also takes a BrokerConnectionDescrptor object that describes the connection parameters fro creating a cluster monitor client. This must be set properly when the system defined client group eventLog is set with ACL information using SSL or access labels.

Creating a BrokerClusterPublisher establishes a connection between your application and one or more Brokers.



Creating a BrokerClientPublisher

Your application can create a BrokerClientPublisher by calling the BrokerClusterPublisher constructor and specifying these parameters.

The name of the host where the Broker to which you want to connect is executing.

The name of the Broker to which you want to connect. You can specify a null value if you want to connect to the default Broker. The default Broker for a particular host is determined by your webMethods Broker administrator.

A unique client ID that identifies your application Broker clients. This identifier cannot be null.

The client group for your application Broker clients. This client group defines the event types your BrokerClusterPublisher can publish or retrieve, as well as the life cycle and queue storage type for your application Broker clients. Client groups are defined by the webMethods Broker administrator.

The name of the application that is creating the BrokerClusterPublisher. This name is used primarily by webMethods Broker administration tools. The application name can be any meaningful string of characters of your choosing.

A BrokerClusterPublisher to be used for the application Broker clients. If you specify a null value, a default connection descriptor will be created for you.

A BrokerClusterPublisher class to be used for the cluster monitor client. If you specify a null value, a default connection descriptor will be created fro you.

A Broker client belonging to eventLog client group, known as the Cluster Monitor Client, is created to the Broker as specified by the constructor parameters. BrokerClusterPublisher discovers other Brokers on the territory via this Cluster Monitor Client and establishes a Broker client connection to each of these Brokers.

Note: BrokerConnectionDescriptor properties such as state sharing, connection sharing, automatic reconnect and other features except the Access Labels and SSL related are ignored for BrokerClusterPublisher.

The following example contains an excerpt from ClusterPublish1.java sample application that shows the creation of a new BrokerClusterPublisher object.

Import COM.activesw.api.client.*; class ClusterPublish1 { static String broker_host = "localhost"; static String broker_name = null; static String client_group = "default"; . . . public static void main(String args[]) { BrokerClusterPublisher bcp; . . . /* Create */ try {



bcp = new BrokerClusterPublisher(broker_host, broker_name, "ClusterPub", client_group, "Cluster Publish Sample #1",null, null); } catch (BrokerException ex) { System.out.println("Error on create cluster publisher\n"+ex); return; } . . .

Client Identifiers

The client identifier is a string that uniquely identifies a Broker client. In the context of BrokerClusterPublisher each of the application Broker client that is created on the territory Brokers will have the same client identifier as specified in the constructor. The Cluster Monitor Client will have a default identifier of CPM- included with the application client identifier.

For more details on Broker client's client identifier refer to “Client Identifiers” on page 42.

Obtaining Client Identifiers

The best way to obtain an identifier of another Broker client is by retrieving the pubId envelope field from an event published by that client, as described in “Obtaining Client Identifiers” on page 42. But you can always use BrokerClusterPublisher.getClientId for obtaining application client identifier and BrokerClusterPublisher.getMonitorClientId for cluster monitor's client ID.

Note: A client identifier cannot start with a # character, nor can it contain / or @ characters. See “Parameter Naming Rules” on page 419 for complete details.

Destroying a BrokerClusterPublisher

The following example contains an excerpt from ClusterPublish1.java sample application that shows the use of destroy method.

BrokerClusterPublisher bcp; . . . /* Destroy */ try { bcp.destroy(); } catch (B rokerException ex) { System.out.println("Error on destroy\n"+ex); return; } . . .



Disconnecting and Reconnecting BrokerClusterPublisher

The webMethods Broker API allows you to disconnect a BrokerClusterPublisher without destroying the underlying Broker client objects. This is only useful if your application Broker client's life cycle is explicit-destroy as the client state for the Broker clients and all the queued events is preserved by the Broker. When the BrokerClusterPublisher reconnects to the Broker, specifying the same client ID, it can continue processing on the same client state. Disconnecting and reconnecting can be particularly useful for applications that want to do batch-style processing at scheduled intervals.

Disconnecting a BrokerClusterPublisher

You can disconnect your BrokerClusterPublisher by calling the BrokerClusterPublisher.disconnect method as shown in the following example. If the application Broker client's life-cycle is destroy-on-disconnect the client state and the event queue storage will be destroyed by the Broker. If it is explicit-destroy, the client state and event queue storage will be preserved until the Broker clients reconnect.

. . . BrokerClusterPublisher bcp; . . . /* Disconnect */ try { bcp.disconnect(); } catch (BrokerException ex) { System.out.println("Error on disconnect\n"+ex); return; } . . .

Reconnecting a BrokerClusterPublisher

You can reconnect to a previously disconnected BrokerClusterPublisher that has a life cycle of explicit-destroy on the application clients by calling BrokerClusterPublisher.reconnect methods specifying the same client ID that was used when the BrokerClusterPublisher was originally created as shown in the following example.

class ClusterPublish1 { static String broker_host = "localhost"; static String broker_name = null; static String client_group = "default"; . . . public static void main(String args[]) { BrokerClusterPublisher bcp; . . . /* Create */ try { bcp = new BrokerClusterPublisher(broker_host, broker_name, "ClusterPub", client_group, "Cluster Publish Sample #1",null, null);



} catch (BrokerException ex) { System.out.println("Error on create cluster publisher\n"+ex); return; } . . . /* Disconnect */ try { bcp.disconnect(); } catch (BrokerException ex) { System.out.println("Error on disconnect\n"+ex); return; } /* Reconnect */ try { bcp = BrokerClusterPublisher.reconnect(broker_host, broker_name, "ClusterPub", client_group, "Cluster Publish Sample #1",null, null); } catch (BrokerException ex) { System.out.println("Error on reconnecting cluster publisher\n"+ex); return; } . . .

Using the newOrReconnect method

You might find it convenient to use the BrokerClusterPublisher.reconnect method to create or reconnect a client when your client application is expected to be executed repeatedly. The newOrReconnect method will attempt to create a BrokerClusterPublisher. If the Broker cluster publishers already exist and was simply disconnected, it will be reconnected.

class ClusterPublish1 { static String broker_host = "localhost"; static String broker_name = null; static String client_group = "default"; . . . public static void main(String args[]) { BrokerClusterPublisher bcp; . . . /* Create */ try { bcp = BrokerClusterPublisher.newOrReconnect(broker_host, broker_name, "ClusterPub", client_group, "Cluster Publish Sample #1",null, null); } catch (BrokerException ex) { System.out.println("Error on newOrReconnect cluster publisher\n"+ex); return; } . . .



Broker Cluster Publisher Connection Notification

The connection notification allows you to register a callback method for a BrokerClusterPublisher. The connection notification is invoked when a Broker client is added or removed from the Broker cluster publisher pool as triggered by the territory change activity on cluster monitor client. The connection notification feature is particularly useful for determining which Broker is available for cluster operations when there is a lot of join or leave activity on the territory.

Note: The connection callback method has a global scope and only a single callback can be active at any given time. Registering a callback cancels the previously registered callbacks. Note that this connection callback on a BrokerClusterPublisher is not the same as the connection callback on a Broker client.

Defining a Connection Callback Object

Use the BrokerCPConnectionCallback interface to derive your own callback object. Your implementation must provide an implementation of the handleConnectionChange callback method. This method indicates the connection change activity within the Broker cluster publisher pool and can be used only for informational purposes apart from logging of the client pool changes.

Registering the Connection Callback Object

Use the BrokerClusterPublisher.registerConnectionCallback method to register a method that you want to be called in the event a Broker client is added or removed from the Broker cluster publisher pool. This method accepts two parameters. The first parameter is the BrokerCPConnectionCallback, it is derived object that implements your callback method. The second parameter is a client_data object, which is used to pass any needed data to the callback method.

Note: Any callback objects previously registered for a client will be replaced by the one currently being registered.

When the BrokerCPConnectionCallback object is the callback method that is invoked, that method's connect_state parameter is set to one of the following BrokerClient defined values shown in the table below. Also, the conn_name is set to the fully-qualified Broker name on which the change occurred.

connect_state Meaning

CONNECT_STATE_DISCONNECTED

The Broker as specified by conn_name has left the territory or down

CONNECT_STATE_CONNECTED

The Broker as specified by conn_name has joined the territory or became available



Canceling the Connection Callback Object

You can un-register a callback by invoking the BrokerClusterPublisher.cancelConnectionCallback.

static class ClusterConnCallback implements BrokerCPConnectionCallback { public void handleConnectionChange(BrokerClusterPublisher bcp, int state, String conn_str, Object client_data) { System.out.print("Connection change on : "+conn_str+ " - "); if (state == BrokerClient.CONNECT_STATE_CONNECTED) System.out.println(" CONNECTED"); else if (state == BrokerClient.CONNECT_STATE_DISCONNECTED) System.out.println(" DISCONNECTED"); } } public static void main(String args[]) { BrokerClusterPublisher bcp; ClusterConnCallback conn_cb; BrokerEvent e; . . . /* create BrokerClusterPublisher */ . . . /* create and register connection callback */ conn_cb = new ClusterConnCallback(); try { bcp.registerConnectionCallback( conn_cb, null) } catch (BrokerException ex) { System.out.println("Error in registering connection callback"); return; } . . . /* operations on BrokerClusterPublisher */ try { bcp.cancelConnectionCallback() } catch (BrokerException ex) { System.out.println("Error in canceling connection callback"); return; } /* disconnect or destroy up BrokerClusterPublisher */ . . . }

Broker Cluster Publisher Selection Notification

The selection notification allows you to register a callback method for a BrokerClusterPublisher that will be invoked whenever a Broker client needs to be chosen from the Broker cluster publisher pool for executing the operation. In the absence of any registered selection callback, BrokerClusterPublisher employs a round robin algorithm to choose Broker client from the Broker cluster publisher pool. If you want to enforce a



certain order or an algorithm for choosing a Broker client, you can register a selection callback object that will be invoked just before choosing a Broker client for a publish/deliver operation.

Note: Selection callback method has a global scope and only a single callback can be active at any given time. Registering a callback will cancel the previously registered callbacks if any exists.

Defining a Selection Callback Object

Use the BrokerCPSelectionCallback interface to derive your own callback object. Your implementation must provide an implementation of the chooseClusterClient method. This method passes-in the list of available Brokers in the form of an array of BrokerInfo objects-a list of Brokers to which a valid Broker client exists in the Broker cluster publisher pool along with the event(s) to be published/delivered. Your algorithm can examine the list of Brokers and the event(s) and choose an index from the BrokerInfo array that represents the Broker client connection you want to use for the current operation. With this index, BrokerClusterPublisher uses the specified Broker client from the Broker cluster publisher pool and executes the operation on that client connection.

Registering the Selection Callback Object

Use the BrokerClusterPublisher.registerSelectionCallback method to register a method to be called for selecting a Broker client from the Broker cluster publisher pool. You must implement both callback methods on this selection callback object; the first one intended for any publish/deliver operation involving a single event and the second one involving operation on multiple events.

This method accepts two parameters. The first parameter is the BrokerCPConnectionCallback, it is a derived object that implements your callback methods. The second parameter is a client_data object, which is used to pass any needed data to the callback method.

Note: Any callback objects previously registered for a BrokerClient will be replaced by the one currently being registered.

Canceling the Selection Callback Object

You can un-register a callback by invoking the BrokerClusterPublisher.cancelConnectionCallback.

static class ClusterSelCallback implements BrokerCPSelectionCallback { int sindex = 0; int mindex = 0;

/* implements a round-robin algorithm on the list of available broker clients */ public int chooseClusterClient(BrokerClusterPublisher bcp,



BrokerEvent[] event, BrokerInfo[] bi, Object client_data) { System.out.println("#of Broker cluster publishers: "+bi.length); for (int i=0;i<bi.length;i++) System.out.print(bi[i].broker_name+" "); mindex = (mindex+1)%bi.length; System.out.println(" ["+bi[mindex].broker_name+"]"); return mindex; }

/* implements a round-robin algorithm on the list of available broker clients */ public int chooseClusterClient(BrokerClusterPublisher bcp, BrokerEvent event, BrokerInfo[] bi, Object client_data) { System.out.println("#of Broker cluster publishers: "+bi.length); for (int i=0;i<bi.length;i++) System.out.print(bi[i].broker_name+" "); sindex = (sindex+1)%bi.length; System.out.println(" ["+bi[sindex].broker_name+"]"); return sindex; } } public static void main(String args[]) { BrokerClusterPublisher bcp; ClusterSelCallback sel_cb; BrokerEvent e; . . . /* create BrokerClusterPublisher */ . . . /* create and register connection callback */ sel_cb = new ClusterSelCallback(); try { bcp.registerSelectionCallback( sel_cb, null) } catch (BrokerException ex) { System.out.println("Error in registering selection callback"); return; } . . . /* operations on BrokerClusterPublisher */ try { bcp.cancelSelectionCallback() } catch (BrokerException ex) { System.out.println("Error in canceling selection callback"); return; } /* disconnect or destroy up BrokerClusterPublisher */ . . . }



Obtaining BrokerClusterPublisher Status

There are a variety of methods you can use to obtain state, status, and statistical information about a BrokerClusterPublisher object.

Use the BrokerClusterPublisher.getApplicationName method to obtain the name of the application associated with this BrokerClusterPublisher.

Use the BrokerClusterPublisher.getClientGroup method to obtain the name of the client group with BrokerClusterPublisher is associated.

Use the BrokerClusterPublisher.getClientId method to obtain the BrokerClusterPublisher client ID.

Use the BrokerClusterPublisher.getMonitorClientId method to obtain the BrokerClusterPublisher Cluster Monitor's client ID.

Use the BrokerClusterPublisher.getTerritoryName method to obtain the name of the territory.

Use the BrokerClusterPublisher.canPublish method to determine whether a BrokerClusterPublisher can publish an event of a specific event type.

Use the BrokerClusterPublisher.getCanPublishNames method to get a list of all event types that can be published by the BrokerClusterPublisher.

Use the BrokerClusterPublisher.getClusterPublisherInfo method to obtain a string that contains information on Broker clients on the Broker cluster publisher pool and other cluster information of the BrokerClusterPublisher in the form of an event.

Use the BrokerClusterPublisher.getClusterPublisherStats method to obtain the statistics on the number of events published, delivered and received along with other useful information of the BrokerClusterPublisher.

Use the BrokerClusterPublisher.toString method to obtain a string that contains information on Broker clients on the Broker cluster publisher pool and other cluster information of the BrokerClusterPublisher.

Use the BrokerClusterPublisher.isConnected method to determine whether a BrokerClusterPublisher is currently connected to a Broker.

Publishing and Delivering Events

A simple publish or deliver operation invoked on the BrokerClusterPublisher object is executed on one of the valid Broker client connections from the Broker cluster publisher pool. If an error occurs during the execution, the operation will be either retried on a different Broker client on the Broker cluster publisher pool or returned as failed with proper exception. A failed operation on a Broker client from the Broker cluster publisher pool will not be retried on the same Broker client. BrokerClusterPublisher will retry on each of the Broker client connections from the cluster pool until the operation succeeds on one of the connections or returns an error when all of the Broker client connections are exhausted.



Creating a New BrokerEvent

Before your BrokerClusterPublisher application can publish or deliver an event it must create the event and set the event's fields. The following example contains an excerpt from the ClusterPublish1.java sample application that shows the creation of a new event. The constructor takes the following parameters:

A BrokerClusterPublisher reference

The name of the event type. In the following example, the event scope is Sample and the event type name is SimpleEvent.

class ClusterPublish1 { static String broker_host = "localhost"; static String broker_name = null; static String client_group = "default"; . . . public static void main(String args[]) { BrokerClusterPublisher bcp; BrokerEvent e; . . . /* Create a BrokerClusterPublisher */ . . . /* Create a BrokerEvent */ try { e = new BrokerEvent( bcp, "Sample::SimpleEvent"); } catch (BrokerException ex) { System.out.println("Error on creating new BrokerEvent \n"+ex); return; } . . .

Field Type Checking

When you create an event with a BrokerClusterPublisher reference, the following field type checking rules are applied to the event.

1 All event fields will be set on the event at the time the event is created.

2 You cannot set a field that does not exist for the event type.

3 You cannot set an event field with a data type other than that defined by the event type.

When you create an event with a null BrokerClusterPublisher reference, the following type checking rules are applied to the event.

1 You can set fields with any field name and any data type.

2 Any attempt to retrieve an event field that was not previously set will cause a BrokerFieldNotFoundException exception to be thrown.



3 After a field has been set, you are not allowed to change the field's type without first clearing the event field, using the BrokerEvent.clearField method or clearing the entire event using the BrokerEvent.clear method.

Publishing Events

When your client application publishes an event, the Broker places it in the event queue of each BrokerClient that has subscribed to that event type. In order for your application to be able to publish an event, it must first create a BrokerClusterPublisher. Your application can then use the BrokerClusterPublisher to create an event, as described in the previous example. After setting the event fields, your application is ready to publish the event.

The client group to which the BrokerClusterPublisher belongs defines the event types the BrokerClusterPublisher can publish. See “Client Groups” on page 39 for more information.

The following example contains an excerpt from the ClusterPublish1.java sample application that shows the use of the BrokerClusterPublish.canPublish method to check for event publication permission. This method requires an event type name.

. . . BrokerClusterPublisher bcp; boolean can_publish; . . . /* Check publish permission */ try { can_publish = bcp.canPublish("Sample::SimpleEvent"); } catch (BrokerException ex) { System.out.println("Error on check for can publish\n"+ex); return; } if (can_publish == false) { System.out.println("Cannot publish event"); System.out.println("Sample::SimpleEvent."); System.out.println("Make sure it is loaded in the broker and"); System.out.println("permission is given to publish it in the"); System.out.println(client_group + " client group."); return; } . . .

You can also use the BrokerClusterPublisher.getCanPublishNames method to obtain the names of all the event types which a BrokerClusterPublisher can publish.

Publishing an Event

After initializing the necessary event fields, your application can publish an event by calling the BrokerClusterPublisher.publish method. The following example contains an excerpt from the ClusterPublish1.java sample application that shows the use of the BrokerClusterPublisher.publish method. This method accepts a BrokerEvent.

BrokerClusterPublisher can publish an event that is targeted for subscribers on the Broker on which the event is published or to all the subscribers on any Broker in the territory.



The following example illustrates how to publish a single event to territory subscribers:

. . . BrokerClusterPublisher bcp; BrokerEvent e; . . . try { bcp.publish(e); } catch (BrokerException ex) { System.out.println("Error on publish\n"+ex); return; } . . .

The following example illustrates how to publish a single event to subscribers on the local Broker only:

. . . BrokerClusterPublisher bcp; BrokerEvent e; . . . try { bcp.localPublish(e); } catch (BrokerException ex) { System.out.println("Error on publish\n"+ex); return; } . . .


Your application can publish several events with one call to the BrokerClusterPublisher.publish method that accepts an array of BrokerEvent objects. The following example contains an excerpt that shows the use of this method, which accepts a BrokerEvent array.

The following example illustrates how to publish multiple events to territory subscribers:

. . . BrokerClusterPublisher bcp; BrokerEvent e[5]; . . . /* Create and initialize the event array */ . . . try { bcp.publish(e); } catch (BrokerException ex) { System.out.println("Error on publish\n"+ex); return; } . . .

The following example illustrates how to publish multiple events to subscribers on the local Broker only:

. . . BrokerClusterPublisher bcp; BrokerEvent e[5];



. . . /* Create and initialize the event array */ . . . try { bcp.localPublish(e); } catch (BrokerException ex) { System.out.println("Error on publish\n"+ex); return; } . . .

Delivering Events

In addition to publishing events to potentially many Broker clients, the webMethods Broker system also allows your application to deliver an event to a single Broker client, through the Broker. In order to deliver an event to a specific Broker client, your application must have the client identifier of that client.

Note: The recipient of a delivered event does not have to register a subscription for the event type being delivered. The recipient only needs to be permitted to receive the delivered event type, as specified by the client group of the receiving Broker client.

You must hard code the client identifier of the recipient, if it is well known.

Delivering an Event

The following example shows the use of the BrokerClusterPublisher.deliver method to deliver a single event. This method accepts these parameters:


The BrokerEvent to be delivered.

The following example illustrates how to deliver a single event:

. . . BrokerClusterPublisher bcp; BrokerEvent e, event; String dest_id = "DestClient"; . . . /* create a BrokerClusterPublisher */ . . . /* create the event to be sent and set the event fields */ . . . /* Deliver the event to the recipient */ try { bcp.deliver( dest_id, e); } catch (BrokerException ex) { System.out.println("Error on delivering event\n"+ex); return; } . . .



Delivering Multiple Events

The following example shows the use of the BrokerClusterPublisher.deliver method to deliver a single event. This method accepts these parameters:


An array of BrokerEvents to be delivered.

The following example illustrates how to deliver multiple events:

. . . BrokerClusterPublisher bcp; BrokerEvent e, event; String dest_id = "DestClient"; . . . /* create a BrokerClusterPublisher */ . . . /* create an array of events to be sent and set the event fields */ . . . /* Deliver events to the recipient */ try { bcp.deliver( dest_id, e); } catch (BrokerException ex) { System.out.println("Error on delivering events\n"+ex); return; } . . .

Request-Reply Model

You can use the request-reply model for applications that publish or deliver a request event to a server application which is expected to return a reply event. The reply event can contain data or can simply be an acknowledgment with no data.

A tag envelope field is set by the BrokerClusterPublisher internally to identify the request event that it is sending. When a server application receives the request event and prepares the reply event, it ensures that the same tag field is set for the reply as was received on the request event. If your requestor sends several different request events, it should set each with a different tag field. When your requestor receives a reply event, it can check the tag field to determine the original request with which the reply is associated. BrokerEvent.getTag and BrokerEvent.setTag methods are used to get and set tag field values from an event.

Using publishRequestAndWait

BrokerClusterPublisher solution does not employ callback mechanism to achieve synchronous request-reply results. Rather it uses publish followed by getEvents approach to implement request-reply mechanism. In this way the automatic failover on the publish operation is available for request-reply model as well.



The following example illustrates how to use BrokerClusterPublisher.publishRequestAndWait for subscribers on the local Broker:

public static void main(String args[]) { BrokerClusterPublisher bcp; BrokerEvent e, events[]; int i; . . . /* create BrokerClusterPublisher */ . . . /* create the request event to be sent and set the event fields */ . . . /* publish the request and wait for a reply */ try { events[] = bcp.localPublishRequestAndWait(e, 6000); } catch (BrokerException ex) { . . . } . . .

The following example illustrates how to use BrokerClusterPublisher().publishRequestAndWait for subscribers in a territory:

public static void main(String args[]) { BrokerClusterPublisher bcp; BrokerEvent e, events[]; int i; . . . /* create BrokerClusterPublisher */ . . . /* create the request event to be sent and set the event fields */ . . . /* publish the request and wait for a reply */ try { events[] = bcp.publishRequestAndWait(e, 6000); } catch (BrokerException ex) { . . . } . . .

Include-Exclude Brokers

At the creation time, the cluster monitor discovers the Brokers on the territory and BrokerClusterPublisher creates BrokerClient connections to these Brokers with the specified application settings. A territory can contain a mixture of Brokers from different versions of webMethods Broker. BrokerClusterPublisher can utilize Brokers from version webMethods Broker 6.0 or higher. All other Brokers are automatically excluded from the cluster operations; therefore, BrokerClusterPublisher automatically excludes pre-6.0 version Brokers at creation time.



You can also exclude or include a specific Broker from cluster operations by invoking BrokerClusterPublisher.excludeBroker method and BrokerClusterPublisher.includeBroker method respectively. If you discover that a set of Brokers have less of a load or the Broker host has more resources than others, you might want to reroute all operations to a specific set of Brokers on the territory.

The following example illustrates how to use BrokerClusterPublisher().exclude and include methods:

public static void main(String args[]) { BrokerClusterPublisher bcp; BrokerEvent e, events[]; int i; . . . /* create BrokerClusterPublisher */ . . . /* create the request event to be sent and set the event fields */ . . . /* When you find that the broker b1 is overloaded and you want to exclude the broker from the cluster operations */ try { bcp.excludeBroker(b1@localhost); } catch (BrokerException ex) { . . . } . . . /* When you find that the broker b1 has returned to normal and you want to include the broker for future cluster operations */ try { bcp.includeBroker(b1@localhost); } catch (BrokerException ex) { . . . } . . .

When a Broker is excluded from on a BrokerClusterPublisher, the Broker client connection to that Broker from the Broker cluster publisher pool is removed immediately so that the Broker client connection can no longer be used. Similarly, after you include the Broker for cluster operations, a new Broker client connection is created so that Broker and future operations will utilize this connection.


15 Working with Basic Authentication

Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 194

Basic Authentication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 194

Configuring the Broker Java Client for Basic Authentication . . . . . . . . . . . . . . . . . . . . . . . . . . . . 194



Overview

This chapter explains how to configure basic authentication support for webMethods Broker clients by writing to the Broker Java Client API.

Basic Authentication

webMethods Broker uses the basic authentication mechanism to allow a client program to provide credentials in the form of a user name and password when making a request to access Broker Server. For more information about basic authentication, please see Administering webMethods Broker.

Configuring the Broker Java Client for Basic Authentication

This section describes how to use the Broker Java client API COM.activesw.api.client.BrokerConnectionDescriptor class to configure and manage basic authentication. This class contains the methods to get and to set basic authentication related settings. For Java APIs, all basic authentication information is passed by the BrokerConnectionDescriptor object. When a BrokerConnectionDescriptor object is created, the default basic authentication settings will be set by reading the corresponding Java property values.

Configuring Basic Authentication by using BrokerConnectionDescriptor Class

For your Java client, use the BrokerConnectionDescriptor.setAuthInfo method described on page to enable basic authentication, prior to creating a BrokerClient.

When a BrokerConnectionDescriptor is created, the authentication information will be set to null by default. Therefore, you must use the setAuthInfo method before creating a Broker client if you want to enable basic authentication.

The following code sample shows how to configure the settings for Broker basic authentication by using the BrokerConnectionDescriptor.setAuthInfo method, passing in the parameters described in the table above:

Return Type Method Signature and Description

void public void setAuthInfo( String username, String password)

Where username is the user name for basic authentication and password is the password for the basic authentication user.

String getAuthUserName()



// Build the connection descriptor. BrokerConnectionDescriptor connectionDescriptor = new BrokerConnectionDescriptor() String username = "sag"; String password = "SoftwareAG123"; // Create a new Broker client. client = new BrokerClient(broker_host, broker_name, client_id,client_group, app_name, connectionDescriptor)

Configuring Basic Authentication by Using System Properties

The following table helps you enable basic authentication by using the system properties on Java clients.

To set this basic authentication property... Set this system property... As shown here...

User name BROKER_CONNECTION_BASIC_AUTH_USER

System.setProperty("BROKER_CONNECTION_BASIC_AUTH_USER","sag");

Password BROKER_CONNECTION_BASIC_AUTH_PASSWORD

System.setProperty("BROKER_CONNECTION_BASIC_AUTH_PASSWORD ", " SoftwareAG123");




16 Working with SSL

Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 198

Broker SSL Security . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 198

Certificate Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 198

Configuring the Broker Java Client for SSL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 199


16 Working with SSL

Overview

This chapter explains how to configure SSL support for webMethods Broker clients by writing to the Broker Java Client API. Information is provided that explains how to:

Authenticate Broker clients.

Manage SSL certificates for Java client applications.

Enable encryption.

Note: When implementing SSL using the Broker Java Client API, you will be using JSSE (Java Secure Sockets Extension) for Broker clients version 7.1 and later. The JSSE library is part of the Java 5 JDK package.

Broker SSL Security

The Broker SSL security model provides the following forms of protection for your event-based Broker Java client applications:

User authentication. Authentication verifies the identity of a Broker Server to a Broker Java client attempting to make a connection and that of the Broker Java client to the Broker Server (two-way authentication). For a connection to be made, both parties must have first been assigned SSL identities.

User authorization for Broker objects protected by Access Control Lists (ACLs). Only clients whose SSL identities are specified in a Broker object's ACL may connect to that object. This type of security protects confidential data from access by unauthorized users.

Encryption of the data traffic between a Broker client and the Broker Server, to protect sensitive data. This type of encryption is independent of the SSL authentication process and of the ACL authorization process. Typically, you encrypt the data traffic when working with highly sensitive data, or to protect data of a confidential nature that passes across a public network.

Certificate Files

To configure SSL for a Broker Java client, you must first store its SSL client certificate information (public certificate/private key pair) in a keystore file, and the trusted root (public certificate of the client certificate issuer, or CA) in a trust store file. These certificates are used to create the Broker Java client's SSL identity.

For the client to make an SSL connection to the Broker Server, you must also have assigned SSL identities to the Broker Server. Once the SSL certificate for the Broker Server is configured, you can create an SSL connection between the Broker Java client and its Broker Server.


16 Working with SSL

Detailed information about creating and managing keystores and trust stores for the Broker Server and the Broker admin component is provided in Administering webMethods Broker.

Configuring the Broker Java Client for SSL

This section describes how to use the Broker Java client API COM.activesw.api.client.BrokerConnectionDescriptor class to configure and manage SSL. This class contains the methods to get and to set SSL-related settings. For Java APIs, all SSL information is passed by the BrokerConnectionDescriptor object. When a BrokerConnectionDescriptor object is created, the default SSL settings will be set by reading the corresponding Java property values.

Configuring SSL Using the BrokerConnectionDescriptor Class

For your Java client, use the BrokerConnectionDescriptor.setSSLCertificate method to configure SSL security, prior to creating a BrokerClient.

When a BrokerConnectionDescriptor is created, the certificate file will be set to null by default. Therefore, you must use the setSSLCertificate method before creating a Broker client if you want to configure SSL security.


void public void setSSLcertificate( string keystore_file, string truststore_file, KeystoreType keystore_type, TruststoreType truststore_type, string password) throws BrokerException;

Where:

keystore_file is the keystore file path.

truststore_file is the truststore file path.

keystore_type is the keystore type.

truststore_type is the trust store type.

password is the password.


16 Working with SSL

The following code sample shows how to configure the settings for Broker SSL authentication using the BrokerConnectionDescriptor.setSSLCertificate method, passing in the parameters described in the previous table:

// Build the connection descriptor. BrokerConnectionDescriptor connectionDescriptor = new BrokerConnectionDescriptor() String keystore_file = “C:\mykeystore.p12”; String truststore_file = “C:\mytruststore.jks”; KeystoreType keystoreType = “KeystoreType.p12”; TruststoreType truststoreType = “TruststoreType.jks”; String password = “1234”; connectionDescriptor.setSSLCertificate (keystore_file, truststore_file, keystoreType, truststoreType, password) // Set other properties for the connectionDescriptor, if needed. // Create a new Broker client.

BrokerSSLCertificate getSSLCertificate( string keystore_file, string truststore_file, KeystoreType keystore_type, TruststoreType truststore_type, string password) throws BrokerException

Where:

keystore_file is the keystore file path.

truststore_file is the truststore file path.

keystore_type is the keystore type.

truststore_type is the trust store type.

password is the password.

Use this method to get the Entrust SSL certificate.

TruststoreType getSSLTruststoreType()

String getSSLTruststore()

KeystoreType getSSLKeystoreType()

String getSSLKeystore()



16 Working with SSL

client = new BrokerClient (brokerHost, brokerName, clientName, clientGroup, ... , “publisher”, connectionDescriptor);

Configuring SSL by Using the System Properties

You can also use the System Properties to configure SSL. The following table helps you configure SSL by using the system properties on Java clients.

Setting Encryption

The BrokerConnectionDescriptor.setSSLEncrypted method allows you to encrypt the data traffic from a Java client to the Broker Server after SSL authentication has taken place.

To set this SSL property... Set this system property... As shown here...

Keystore BROKER_CONNECTION_SSL_KEYSTORE

System.setProperty("BROKER_CONNECTION_SSL_KEYSTORE", "C:\mykeystore.p12");

Truststore BROKER_CONNECTION_SSL_TRUSTSTORE

System.setProperty("BROKER_CONNECTION_SSL_TRUSTSTORE", "C:\mytruststore.jks");

Keystore Type BROKER_CONNECTION_SSL_KEYSTORE_TYPE

System.setProperty("BROKER_CONNECTION_SSL_KEYSTORE_TYPE", "KeystoreType.p12");

Truststore Type

BROKER_CONNECTION_SSL_TRUSTSTORE_TYPE

System.setProperty("BROKER_CONNECTION_SSL_TRUSTSTORE_TYPE", "TruststoreType.jks");

Ciphersuites BROKER_CONNECTION_SSL_CIPHERSUITES

System.setProperty("BROKER_CONNECTION_SSL_CIPHERSUITES", "TLS_RSA_WITH_AES_128_CBC_SHA");

Password BROKER_CONNECTION_SSL_PASSWORD

System.setProperty("BROKER_CONNECTION_SSL_PASSWORD", "SoftwareAG123");

Provider BROKER_CONNECTION_SSL_PROVIDER

System.setProperty("BROKER_CONNECTION_SSL_PROVIDER", "Entrust");

DN BROKER_CONNECTION_SSL_DN

System.setProperty("BROKER_CONNECTION_SSL_DN", "cn=brokerclient1, o=webM,st=CA,c=US");

FIPS BROKER_CONNECTION_SSL_FIPS

System.setProperty("BROKER_CONNECTION_SSL_FIPS", "true");

TCP No Delay BROKER_CONNECTION_TCP_NODELAY

System.setProperty("BROKER_CONNECTION_TCP_NODELAY", "true");


16 Working with SSL

Important! When a BrokerConnectionDescriptor object is created, by default, its encryption flag is set to true.

To control whether to use data encryption, invoke the setSSLEncrypted method on the BrokerConnectionDescriptor object before creating your Broker client. Use a setting of true to enable encryption, and false to disable encryption, as shown in the example below (the "on" setting is commented out):

/* Configure encryption */ try { connectionDescriptor.setSSLEncrypted( false ); // Encryption = OFF // connectionDescriptor.setSSLEncrypted( true ); // Encryption = ON catch (BrokerException ex) { System.out.println(“Error on setSSLEncrypted.\n”+ex); return; }

Retrieving a Broker Server's Certificate

You can use the BrokerClient.getBrokerSSLCertificate method to obtain information about the SSL certificate of the Broker Server to which your Broker client is connected. A getBrokerSSLCertificate object is returned by this method and contains information such as the Broker's distinguished name and the certificate authority that issued the Broker's certificate.

Enabling FIPS in Java Clients

You can enable FIPS mode only if your SSL provider is Entrust. Perform the following steps to enable the FIPS mode in Java clients.

To enable FIPS mode in client

1 Set the SSL provider system property BROKER_CONNECTION_SSL_PROVIDER, to Entrust as follows:

System.setProperty("BROKER_CONNECTION_SSL_PROVIDER", "Entrust");

2 To enable the FIPS mode, set the system property, BROKER_CONNECTION_SSL_FIPS to true as follows.

System.setProperty("BROKER_CONNECTION_SSL_FIPS","true");


17 Java API Client Reference

BrokerCallback . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 203

BrokerClient . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 204

BrokerClientPoll . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 273

BrokerClusterPublisher . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 277

BrokerConnectionCallback . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 295

BrokerConnectionDescriptor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 296

BrokerCPConnectionCallback . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 314

BrokerCPSelectionCallback . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 314

BrokerDate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 316

BrokerEvent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 324

BrokerException . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 365

BrokerField . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 367

BrokerFilter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 367

BrokerFormat . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 370

BrokerMonitorClient . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 377

BrokerSSLCertificate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 381

BrokerSubscription . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 382

BrokerTransactionalClient . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 384

BrokerTypeCache . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 406

BrokerTypeDef . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 407

BrokerCallback

interface BrokerCallback extends java.lang.Object

This interface allows you to register callback methods for handling events received by a Broker client. Use this interface to derive your own callback object and then provide an implementation for the abstract method handleBrokerEvent, which will be invoked to handle a specific event type received by your Broker client. For more information on callbacks, see “Using the Callback Model” on page 59.



The callback mechanism can only be used with the BrokerClient.mainLoop, BrokerClient.dispatch, and BrokerClient.threadedCallbacks methods.

handleBrokerEventboolean handleBrokerEvent( BrokerClient client, BrokerEvent event, Object client_data);

You must provide the implementation of this method. This method will be invoked for the client to handle the received event. The parameter client_data represents any data which this method will need in order to process the event.

Your method implementation should return true if its processing was successful or false if a failure occurred. If true is returned, the event will be acknowledged automatically. For information on acknowledging events, see “Using Sequence Numbers” on page 145.

Note: The event should not be modified, due to the fact that it can be passed to other callback methods.

BrokerClient

class BrokerClient extends java.lang.Object

This class represents a connection between a client application and a Broker Server. Your client application can create one or more BrokerClient objects. All BrokerClient objects connected to the same host will share a single connection to the Broker, unless otherwise specified in the constructor.

Constants

This class contains the following constants:

client The Broker client for which the callback is being registered.

event The event being passed to the callback.

client_data The used-defined data that was passed to the callback registration.

Name Description

ACK_AUTOMATIC Used with the deliverWithAck and publishWithAck methods.

ACK_NONE Used with the deliverWithAck and publishWithAck methods.



ACK_THROUGH Used with the deliverWithAck and publishWithAck methods.

ACK_SELECTIVE Used with the deliverWithAck and publishWithAck methods.

CONNECT_STATE_CONNECTED Indicates that the Broker client is currently connected. Used with connection callbacks, described on registerConnectionCallback on page 268.

CONNECT_STATE_DISCONNECTED Indicates that the Broker client is currently disconnected. Used with connection callbacks, described on registerConnectionCallback on page 268.

CONNECT_STATE_RECONNECTED Indicates that the Broker client was disconnected, but was automatically reconnected. Used with connection callbacks, described on registerConnectionCallback on page 268.

DO_NOT_ACK Used with methods like getEvents to indicate that no acknowledgment is to be sent for the events which have been received.

NO_SHARE_LIMIT Used with the getStateShareLimit and setStateShareLimit methods to indicate there is no limit on state sharing.

REPLY_FLAG_CONTINUE Used when delivering reply events, see deliverPartialReplyEvents on page 222, to indicate that more replies are pending.

REPLY_FLAG_END Used when delivering reply events, see deliverPartialReplyEvents on page 222, to indicate that no more replies will be sent.

REPLY_FLAG_START Used when delivering reply events, see deliverPartialReplyEvents on page 222, to indicate the beginning of the series of reply events.

REPLY_FLAG_START_AND_END Used when delivering reply events, see deliverPartialReplyEvents on page 222, to indicate the entire series of reply events is being sent.

TIME_INFINITE Used with methods that accept a time-out value to indicate the method should not time-out, but should block until the operation completes.

Name Description



Constructor

BrokerClient

BrokerClient( String broker_host, String broker_name,

TRANSACTION_LEVEL_ANY Used by the beginTransaction method to request any of the following levels of transaction support from an adapter.

TRANSACTION_LEVEL_BASIC Used by the beginTransaction method to request basic transaction support. For more information, see “Transaction Semantics” on page 121.

TRANSACTION_LEVEL_CONVERSATIONAL Used by the beginTransaction method to request conversational transaction support. For more information, see “Transaction Semantics” on page 121

TRANSACTION_LEVEL_PSEUDO Used by the beginTransaction method to request pseudo transaction support.

TRANSACTION_MODE_COMMIT Used by the endTransaction method to commit a transaction.

TRANSACTION_MODE_ROLLBACK Used by the endTransaction method to rollback a transaction to the last save point or to the beginning of the transaction.

TRANSACTION_MODE_SAVEPOINT Used by the endTransaction method to set a save point for a transaction.

VERSION_31

VERSION_40

VERSION_50

VERSION_60

VERSION_61

VERSION_62

VERSION_63

VERSION_64

VERSION_65

VERSION_66

Name Description



String client_id, String client_group, String app_name, BrokerConnectionDescriptor desc);

Creates a BrokerClient object with an empty event queue and no event subscriptions. The application is responsible for invoking the disconnect or destroy method when the BrokerClient is no longer needed.

broker_host The name of the host running the Broker that the new Broker client will use. Specified in the form <broker_host_name>:<port_number>. If you omit the port number, the default port number will be used. For example: MyHost:12000

broker_name The name of the Broker to which the new Broker client will be connected. If null, the default Broker will be used. See “Parameter Naming Rules” on page 419 for restrictions on Broker names.

client_id A string containing a unique identifier for the new Broker client to be used when disconnecting or reconnecting. If null, the Broker will generate a unique client identifier. A null value is usually supplied for Broker clients whose life cycle is destroy-on-disconnect. See “Client Identifiers” on page 42 and “Parameter Naming Rules” on page 419 for more information.

client_group The name of the client group for the new Broker client. See “Parameter Naming Rules” on page 419 for restrictions on client group names.

app_name The name of the application that will contain the new Broker client.

desc The connection descriptor to use for the new Broker client. If null, a default connection will be established for the new Broker client, which can be shared with other Broker clients.

Possible Exceptions Meaning

BrokerClientExistsException Another Broker client is already using the specified client_id.



See also: BrokerClient.destroy,BrokerClient.disconnect, BrokerClient.newOrReconnect, and BrokerClient.reconnect

BrokerClientQueueBrowserException An operation pertaining to the creation or access of a queue browser failed. This exception wraps all queue browser related errors into a single exception for convenience, with the minor codes on the exception detailing the specifics of the failure. This exception is thrown for errors on both client and admin queue browser.

BrokerCommFailureException A problem occurred establishing the connection.

BrokerHostNotFoundException The specified broker_host does not exist.

BrokerInvalidClientIdException The client_id contains invalid characters.

BrokerInvalidNameException The app_name parameter contains invalid characters.

BrokerNoPermissionException Permission to join the client_group was denied.

BrokerNotRunningException A Broker could not be found on the broker_host.

BrokerNullParameterException The broker_host, client_group, or app_name parameter is null.

BrokerSecurityException A secure connection was attempted, but was rejected by the Broker.

BrokerUnknownBrokerNameException The specified broker_name does not exist. If broker_name was null, then this exception indicates that a default Broker has not been set on the specified Broker host.

BrokerUnknownClientGroupException The specified client_group does not exist on the Broker.




Methods

acknowledge Methods

acknowledge

void acknowledge( long seqn) throws BrokerException

Acknowledges the receipt of a single event, specified by seqn, for this BrokerClient. If seqn is set to zero, all previously unacknowledged events are acknowledged. By acknowledging one or more events, a BrokerClient ensures that the Broker will not send those events again.

See also: BrokerClient.acknowledgeThrough and BrokerEvent.getReceiptSequenceNumber

acknowledge

void acknowledge( long[] seqn throws BrokerException

Acknowledge the array of events with the given seqn numbers. A value of zero acknowledges all outstanding events. In addition to the listed exceptions, any communications exception can be thrown.

seqn The event sequence number that is being acknowledged. A value of 0 will acknowledge all events received that were previously not acknowledged.


BrokerInvalidAcknowledgementException

The seqn was not a valid event to acknowledge.

BrokerInvalidClientException The client has been destroyed or disconnected.

BrokerOutOfRangeException The seqn was less than zero.

seqn The event sequence number that is being acknowledged. A value of 0 will acknowledge all events received that were previously not acknowledged.







See also: BrokerClient.acknowledgeThrough and BrokerEvent.getReceiptSequenceNumber

acknowledgeThrough

void acknowledgeThrough( long seqn) throws BrokerException

Acknowledges the receipt of all events received by this BrokerClient, up to and including the event with the sequence number specified by seqn. If seqn is set to 0, all previously unacknowledged events are acknowledged. By acknowledging the events it has received, a BrokerClient ensures that the Broker will not send those events again. To acknowledge a single event, use the acknowledge method.

See also: BrokerClient.acknowledge and BrokerEvent.getReceiptSequenceNumber

begin Methods

beginAdapterTransaction

public int beginAdapterTransaction( java.lang.String transaction_id, int required_level, java.lang.String[] participants, boolean want_ack) throws BrokerException

Publishes an Adapter::beginTransaction event for the given transaction ID. After sending this event, the application can send any number of additional events with the "_env.transactionId" field set to the specified transaction ID. When it is done, it should use the endTransaction() method to close the transaction. required_level should be set to one of the TRANSACTION_LEVEL_* values. If set to something other than TRANSACTION_LEVEL_ANY, adapters which do not support the required level should generate an error on the first event they receive from this transaction. participants can be


seqn The last event sequence number that is being acknowledged. A value of 0 will acknowledge all events received that were previously not acknowledged.









null. If any participants are specified, then only those clients should interact with the request events. These are usually adapter names. If want_ack is false, this function returns 0. Otherwise, it returns the value of the tag used in the beginTransaction event. In addition to the listed exceptions, any communications exception can be thrown.

beginTransaction (deprecated)

int beginTransaction( String transaction_id, int required_level, String participants[], boolean want_ack throws BrokerException

Publishes an Adapter::beginTransaction event for the specified transaction identifier. Returns zero if want_ack is false and no acknowledgment will be sent. If want_ack is true, returns the tag value of the event published so that you can match it to the acknowledgment that will follow.

If required_level is set to a value other than TRANSACTION_LEVEL_ANY, then adapters which do not support the required level should generate an error for the first event they receive for this transaction.

After invoking this method, your application can send any number of additional events with the transactionId envelope field set to the specified transaction identifier.



BrokerNoPermissionException The client does not have permission to publish the Adapter::beginTransaction event type.

BrokerNullParameterException The transaction_id is null, or if any entry in participants is null.

transaction_id The identifier for this transaction, allocated using the makeTransactionId method.

required_level Indicates the requested level of the transaction being started, specified as one of the TRANSACTION_LEVEL_* values in “Constants” on page 204.

participants An array of client identifiers that indicates which clients are allowed to interact with events contained in the transaction.

want_ack If true, indicates that a reply is requested and the tag value of this event is returned.



You should use the endTransaction method to close the transaction.

See also: BrokerClient.endTransaction and BrokerClient.makeTransactionId

can Methods

canPublish

boolean canPublish( String event_type_name) throws BrokerException

Returns true if this Broker client is allowed to publish the event_type_name; otherwise false is returned. A Broker client's publication permissions are determined by the client group to which it belongs. See Administering webMethods Broker for more information.

See also: BrokerClient.canSubscribe and BrokerClient.publish

canSubscribe

boolean canSubscribe( String event_type_name) throws BrokerException



BrokerNoPermissionException The client does not have permission to publish the Adapter::beginTransaction event type.

BrokerNullParameterException The transaction_id parameter is null.

event_type_name The name of the event that this Broker client wants to publish.



BrokerNullParameterException The event_type_name parameter is null.

BrokerUnknownEventTypeException The event type does not exist on the Broker.

event_type_name The name of the event to which this Broker client wants to subscribe.



Returns true if this Broker client is allowed to subscribe to the event_type_name, otherwise false is returned. This method can also be used to determine the types of events that can be delivered to this BrokerClient.

A Broker client's subscription permissions are determined by the client group to which it belongs. See Administering webMethods Broker for more information.

See also: BrokerClient.canPublish, BrokerClient.newSubscription, and BrokerClient.newSubscriptions

cancel Methods

cancelCallbackForSubId

void cancelCallbackForSubId(int sub_id) throws BrokerException

Cancels the callback method that has been registered for the specified subscription identifier for this Broker client.

See also: BrokerClient.cancelCallbacks, BrokerClient.registerCallback, and BrokerClient.registerCallbackForSubId

cancelCallbackForTag

void cancelCallbackForTag(int tag) throws BrokerException

Cancels a callback method that was registered for the specified tag for this Broker client.





sub_id The subscription identifier associated with the callback method to be cancelled.



tag The tag associated with the callback method to be cancelled.



See also: BrokerClient.cancelCallbacks, BrokerClient.registerCallback, and BrokerClient.registerCallbackForTag

cancelCallbacks

void cancelCallbacks() throws BrokerException

Cancels all callback methods that have been registered for this BrokerClient object.

See also: BrokerClient.cancelCallbackForSubId, BrokerClient.cancelCallbackForTag, BrokerClient.registerCallback, BrokerClient.registerCallbackForSubId, and BrokerClient.registerCallbackForTag

cancelCheckForEvents

void cancelCheckForEvents() throws BrokerException

Interrupts a thread on the current Broker client session that is currently blocked on a check for events call, then cancels the associated pending check events request on the current Broker client queue. If there is no such request, the call simply returns. This operation is intended for use in multi-threaded clients. This function is safe for use in a signal handler.

See also: BrokerClient.checkForEvents and BrokerClient.interruptCheckForEvents

cancelSubscription

void cancelSubscription( String event_type_name, String filter) throws BrokerException







event_type_name The event type name associated with the subscription. See “Parameter Naming Rules” on page 419 for restrictions on event type names.



Cancels the subscription with the matching event_type_name and filter.

You can add a wildcard character "*" to the end of the event_type_name to cancel multiple subscriptions within a particular event type scope. See “Using Wildcards” on page 92 for more information.

See also: BrokerClient.cancelSubscriptions, BrokerClient.doesSubscriptionExist, BrokerClient.getSubscriptions, BrokerClient.newSubscription, and BrokerClient.newSubscriptions

cancelSubscription

void cancelSubscription( BrokerSubscription sub) throws BrokerException

Cancels a subscription, specified by the sub object, for this BrokerClient. Only the event_type_name and filter members of the BrokerSubscription object are used to find a matching subscription to cancel; the subId member is ignored.

See also: BrokerClient.cancelSubscriptions, BrokerClient.getSubscriptions, BrokerClient.newOrReconnect, and BrokerClient.newSubscriptions

cancelSubscriptions

void cancelSubscriptions( BrokerSubscription subs[]) throws BrokerException

filter The filter string associated with the subscription. Set to null if no filter string was specified in the original subscription.



BrokerInvalidSubscriptionException There was no existing subscription that matched event_type_name and filter.


sub The subscription to be cancelled, consisting of a subscription identifier, an event type name, and a filter.



BrokerInvalidSubscriptionException There was no existing subscription that matched sub.

BrokerNullParameterException The sub or sub.event_type_name is null.



Cancels all of the subscriptions, specified by subs, for this BrokerClient. Only the event_type_name and filter fields of the BrokerSubscription objects are used to find a matching subscription to cancel; the subId field is ignored.

See also: BrokerClient.cancelSubscriptions, BrokerClient.getSubscriptions, BrokerClient.newSubscription, and BrokerClient.newSubscriptions

check Method

checkForEvents

void checkForEvents( int milliseconds) throws BrokerException

Checks for the availability of deliverable events on the Broker client's queue. If one or more deliverable events are available, the call returns immediately. If no deliverable events are available, the method blocks the calling thread and creates a check events request on the queue that waits for the number of milliseconds specified by milliseconds. If deliverable events become available within the wait period, the call returns with no error. If the wait period times out before any deliverable events become available, the method throws a timeout exception. The interruptCheckForEvents() method can interrupt a pending check events request that is currently blocked and the cancelCheckForEvents() method can cancel a pending check events request. In addition to the listed exceptions, the method can throw any communications exception.

subs An array of subscriptions to be cancelled. See BrokerSubscription on page 382 for more information.



BrokerInvalidSubscriptionException There was no existing subscription that matched one or more of the subscriptions in subs.

BrokerNullParameterException The subs or any of its elements is null, or one of the element's event_type_name field is null.

milliseconds The number of milliseconds for a pending check events request to wait on the Broker client's queue. A value of -1 or TIME_INFINITE specifies an infinite time period.



See also: BrokerClient.interruptCheckForEvents and BrokerClient.cancelCheckForEvents

clear Method

clearQueue

void clearQueue() throws BrokerException

Clears all events in the queue for the specified client.

Important! Use this method with care because it deletes events that have not yet been processed by the Broker client.

See also: BrokerClient.getQueueLength

create Method

createClientQueueBrowser

createClientQueueBrowser() throws BrokerException

Create a client queue browser on the client's queue, so that a client can inspect its own queue contents without requiring any administrative privileges. This queue browser does not lock the client queue and can only be used for browsing the queue contents.


BrokerInterruptedException The BrokerClient.interruptCheckForEvents method was used to stop the call.


BrokerInvalidOperationException The method tried to create a pending check events request, but the client already has a pending check or get events request.

BrokerOutOfRangeException The milliseconds parameter is less than -1.

BrokerTimeoutException The wait period timed out before a deliverable event arrived on the queue.





Returns a BrokerClientQueueBrowser object if successful, otherwise throws a BrokerException. See the webMethods Broker Administration Java API Programmer’s Guide for more information about queue browsers.

deliver Methods

deliver

void deliver( String dest_id, BrokerEvent event) throws BrokerException

Sends the event to the Broker client with a client identifier of dest_id. The Broker client that is to receive the delivered event is not required to have registered a subscription for the event type, but its client group must allow the client to receive the event type.

Note: No exception will be thrown if the recipient, represented by dest_id, no longer exists.

A typical use of this function is when your Broker client replies to a request event from another Broker client. In such a case, you can obtain the dest_id by extracting it from the envelope of the request event, as described on the example in “Obtaining the Client Identifier” on page 134.


BrokerIncompatibleVersionException An attempt was made to create a queue browser on a pre 6.5 Broker client, which does not support queue browsers.

BrokerInvalidClientException The client has been already destroyed.

BrokerClientQueueBrowserException A client queue browser is already open on the client queue from the same session.

dest_id The client identifier of the Broker client that is to receive the event.

event The BrokerEvent object to be delivered.


BrokerInvalidClientException This BrokerClient has been destroyed or disconnected.

BrokerInvalidClientIdException This dest_id contains invalid characters.

BrokerInvalidEventException The event does not match its type definition.

BrokerNoPermissionException The client does not have permission to publish the event type.

BrokerNullParameterException The dest_id or event parameter is null.



See also: BrokerClient.deliverAckReplyEvent, BrokerClient.deliverErrorReplyEvent, BrokerClient.deliverPartialReplyEvents, BrokerClient.deliverReplyEvent, BrokerClient.deliverReplyEvents, BrokerClient.deliverWithAck, BrokerClient.publish, and BrokerClient.publishWithAck

deliver

void deliver( String dest_id, BrokerEvent events[]) throws BrokerException

Delivers the array of events to the Broker client with a client identifier of dest_id.

Note: No exception will be thrown if the recipient, represented by dest_id, no longer exists.

See also: BrokerClient.deliverAckReplyEvent, BrokerClient.deliverErrorReplyEvent, BrokerClient.deliverPartialReplyEvents, BrokerClient.deliverReplyEvent, BrokerClient.deliverReplyEvents, BrokerClient.deliverWithAck, BrokerClient.publish, and BrokerClient.publishWithAck


dest_id The client identifier of the Broker client that is to receive the events.

events The array of BrokerEvent objects to be delivered.




BrokerInvalidEventException One or more of the events does not match its type definition.

BrokerNoPermissionException The client does not have permission to publish all of the event types.

BrokerNullParameterException The dest_id or events parameter is null, or one or more of the events does not exist on the Broker.

BrokerUnknownEventTypeException One or more of the event types does not exist on the Broker.




deliverAckReplyEvent

void deliverAckReplyEvent( BrokerEvent request_event, long publish_seqn) throws BrokerException

Delivers an Adapter::ack event to the originator of the specified request_event. This method properly sets the tag envelope field to match that of the request.

If the trackId envelope field was set on request_event, that value is copied to the Adapter::ack event. If the request_event trackId envelope field was not set, the pubId envelope field from the request_event will be used instead.

The client that is to receive the delivered event is not required to have registered a subscription for the event type, but its client group must allow the client to receive the event type.

Note: No exception will be thrown if the recipient, represented by the pubId field in request_event, no longer exists.

See also: BrokerClient.deliver, BrokerClient.deliverErrorReplyEvent, BrokerClient.deliverPartialReplyEvents, BrokerClient.deliverReplyEvent, BrokerClient.deliverReplyEvents, and BrokerClient.deliverWithAck

deliverErrorReplyEvent

void deliverErrorReplyEvent( BrokerEvent request_event, BrokerEvent error_event) throws BrokerException

request_event The original request event containing the client ID of the sender of the original request.

publish_seqn The publish sequence number to use on the reply event. Should be set to zero if you are not using publish sequence numbers.



BrokerInvalidEventException The request_event was not received from the Broker, but was created locally.

BrokerNoPermissionException The client does not have permission to publish the event type Adapter::ack.

BrokerNullParameterException The request_event parameter is null.

request_event The request event for which this null reply is being generated.

error_event The error event to be delivered.



Sends a single error event to the Broker in reply to the Broker client that published the request_event. This function properly sets the tag, appSeqn, and appLastSeqn envelope fields.

If the trackId envelope field was set on request_event, that value is copied to the error_event. If the request_event trackId envelope field was not set, the pubId envelope field from the request_event will be used instead.

The error_event will be delivered to the Broker client with the client ID contained in the errorsTo envelope field of request_event, if it was set by the requestor.


See also: BrokerClient.deliver, BrokerClient.deliverAckReplyEvent, BrokerClient.deliverErrorReplyEvent, BrokerClient.deliverPartialReplyEvents,BrokerClient.deliverReplyEvent, BrokerClient.deliverReplyEvents, and BrokerClient.deliverWithAck

deliverNullReplyEvent

void deliverNullReplyEvent( BrokerEvent request_event, String reply_event_type_name, long publish_seqn) throws BrokerException



BrokerInvalidEventException The request_event was not received from the Broker, or error_event does not match its event type.

BrokerNoPermissionException The client does not have permission to publish the error_event type.

BrokerNullParameterException The request_event or error_event parameter is null.

BrokerUnknownEventTypeException The error_event type does not exist on the Broker.

request_event The request event for which this null reply is being generated.

reply_event_type_name The event type name of the null reply event to be sent. See “Parameter Naming Rules” on page 419 for restrictions on event type names.



Delivers a null event of type reply_event_type_name to the publisher of the request_event, which is probably a request event. Null reply events indicate that a request was successful and resulted in no data.

The envelope tag, appSeqn, and appLastSeqn fields are set to indicate that this is a null event.

If the trackId envelope field was set on request_event, that value is copied to the null reply event. If the request_event trackId envelope field was not set, the pubId envelope field from the request_event will be used instead.


See also: BrokerClient.deliver, BrokerClient.deliverAckReplyEvent, BrokerClient.deliverPartialReplyEvents, and BrokerClient.deliverWithAck

deliverPartialReplyEvents

int deliverPartialReplyEvents( BrokerEvent request_event BrokerEvent events[], int flag, int token) throws BrokerException

publish_seqn The publish sequence number for the reply event. Set to zero if your application is not using publish sequence numbers.




BrokerNoPermissionException The client does not have permission to publish the reply event type.

BrokerNullParameterException The request_event or reply_event_type_name parameter is null.

BrokerUnknownEventTypeException The reply event type does not exist on the Broker.

request_event The event for which the partial reply is being generated.

events The array of reply events that are to be delivered



Delivers an array of events to the Broker to be delivered to the Broker client that originally published request_event. Either all of the events or none of them will be delivered. This method properly sets the tag, appSeqn, and appLastSeqn envelope fields.

If the trackId envelope field was set on request_event, that value is copied to the reply events. If the request_event trackId envelope field was not set, the pubId envelope field from the request_event will be used instead.


This method is used to deliver parts of a set of replies in groups. When called the first time, flag should be REPLY_FLAG_START. After doing this, additional calls can be made with other flag values. During intermediate replies, flag should be REPLY_FLAG_CONTINUE. On the final call, flag should be REPLY_FLAG_END and n must be at least 1.

Calling this method with flag set to REPLY_FLAG_START_AND_END allows the entire result to be passed to this method in one call.

The reply_token value exists to carry information between calls and has no meaning to the caller. The reply_token can be anything if flag is set to REPLY_FLAG_START, but in all other cases it should be set to the value returned by the previous invocation of this method.

See also: BrokerClient.deliver, BrokerClient.deliverAckReplyEvent, BrokerClient.deliverErrorReplyEvent, BrokerClient.deliverReplyEvent, BrokerClient.deliverReplyEvents, and BrokerClient.deliverWithAck

flag Indicates if there are more events to be sent as part of this reply. Must be one of: REPLY_FLAG_START, REPLY_FLAG_CONTINUE, REPLY_FLAG_START_AND_END, or REPLY_FLAG_END.

token A temporary value used by the method as temporary storage between invocations.



BrokerInvalidEventException The request_event was not received from the Broker, but was created locally.

BrokerNoPermissionException The client does not have permission to publish all of the reply event types.

BrokerNullParameterException The request_event or events parameter is null, or any element in events is null.

BrokerOutOfRangeException The flag parameter is invalid.

BrokerUnknownEventTypeException The event type for any of the reply events does not exist on the Broker.



deliverReplyEvent

void deliverReplyEvent( BrokerEvent request_event, BrokerEvent event) throws BrokerException

Sends a single event to the Broker for delivery to the client that published request_event. This method properly sets the tag, appSeqn, and appLastSeqn envelope fields.

If the trackId envelope field was set on request_event, that value is copied to the reply event. If the request_event trackId envelope field was not set, the pubId envelope field from the request_event will be used instead.


See also: BrokerClient.deliver, BrokerClient.deliverAckReplyEvent, BrokerClient.deliverErrorReplyEvent, BrokerClient.deliverPartialReplyEvents, BrokerClient.deliverReplyEvents, and BrokerClient.deliverWithAck

deliverReplyEvents

void deliverReplyEvents( BrokerEvent request_event, BrokerEvent events[]) throws BrokerException

request_event The request event for which the reply is being generated.

event The event to be sent.



BrokerInvalidEventException The request_event was not received from the Broker, or the reply event does not match its event type.

BrokerNoPermissionException The client does not have permission to publish the reply event type.

BrokerNullParameterException The request_event or event parameter is null.

BrokerUnknownEventTypeException The reply event type does not exist on the Broker.

request_event The request event for which the reply is being generated.

events The array of events to be sent.



Sends the array of events to the Broker for delivery to the client that published request_event. Either all of the events or none of them are delivered. This method properly sets the tag, appSeqn, and appLastSeqn envelope fields.

If the trackId envelope field was set on request_event, that value is copied to the reply events. If the request_event trackId envelope field was not set, the pubId envelope field from the request_event will be used instead.

This method assumes that the entire set of reply events is being delivered at once.


See also: BrokerClient.deliver, BrokerClient.deliverAckReplyEvent, BrokerClient.deliverErrorReplyEvent, BrokerClient.deliverPartialReplyEvents, BrokerClient.deliverReplyEvent, and BrokerClient.deliverWithAck

deliverRequestAndWait

BrokerEvent[] deliverRequestAndWait( String dest_id, BrokerEvent event, int msecs) throws BrokerException

Sends the event to the Broker for delivery to the client with the specified dest_id and then waits for all reply events to be received. The last reply event is detected when an event is received with the envelope fields appSeqn and appLastSeqn being equal.



BrokerInvalidEventException The request_event was not received from the Broker, or at least one of the reply events does not match its defined event type.

BrokerNoPermissionException The client does not have permission to publish all of the reply event types.

BrokerNullParameterException The request_event or events parameter is null, or any element in events is null.

BrokerUnknownEventTypeException The event type for any of the reply events does not exist on the Broker.

dest_id The destination identifier of the Broker client to receive the event.

event The event to be delivered.

msecs The number of milliseconds to wait for a reply event to process before timing out. If set to TIME_INFINITE, this method will wait indefinitely.



This method creates a value for the tag envelope field using BrokerClient.makeTag method. This method blocks until the replies are received or until the time-out interval expires.

Note: You must register a general callback object, using the BrokerClient.registerCallback method, before invoking this method. Also note that an exception will not be thrown if the recipient, represented by dest_id, no longer exists.

See “Using Request-Reply” on page 107 for more information on using the request-reply model.

See also: BrokerClient.deliverReplyEvents, BrokerClient.publishRequestAndWait, and BrokerEvent.isLastReply

deliverWithAck

void deliverWithAck( String dest_id, BrokerEvent events[], int ack_type, long ack_seqn[]) throws BrokerException


BrokerBadStateException This method was called from a callback method.


BrokerInvalidClientIdException The dest_id contains invalid characters.

BrokerInvalidEventException The event does not match its event type.


BrokerNullParameterException The dest_id or event parameter is null.

BrokerUnknownEventTypeException The event type for the reply event does not exist on the Broker.

dest_id The client identifier of the Broker client that is to receive the events


ack_type Determines how the events will be acknowledged and must be set to one of the following:

ACK_NONE

ACK_AUTOMATIC

ACK_THROUGH

ACK_SELECTIVE



Sends the array of events to the Broker for delivery to the Broker client destination specified by dest_id. You also have one of several options for acknowledging events already received by this client. Either all events or none will be delivered.

Note: An exception will not be thrown if the recipient, represented by dest_id, no longer exists.

The setting of the ack_type and ack_seqn parameters will determine which events received by this client are to be acknowledged.

ack_seqn The array of sequence numbers to be acknowledged if ack_type is set to ACK_THROUGH or ACK_SELECTIVE.

ack_type ack_seqn Result

ACK_NONE Not applicable. No events are acknowledged.

ACK_AUTOMATIC Not applicable. All events received by the client are acknowledged.

ACK_THROUGH ack_seqn[0] contains the sequence number of the last event to be acknowledged. If set to 0, the behavior will be the same as ACK_AUTOMATIC

Acknowledges all events up to and including the sequence number specified by ack_seqn[0]. If the n_acks argument is zero, no events will be acknowledged.

ACK_SELECTIVE ack_seqn contains the sequence numbers of the specific events to be acknowledged.

Acknowledges the specific events whose sequence numbers are contained in ack_seqn. All sequence numbers must be greater than zero.



The parameter ack_seqn contained an invalid sequence number. The events were not sent to the Broker.



BrokerInvalidEventException One or more of the events does not match its type definition.



See also: BrokerClient.deliver, BrokerClient.deliverAckReplyEvent, BrokerClient.deliverErrorReplyEvent, BrokerClient.deliverPartialReplyEvents, BrokerClient.deliverReplyEvent, BrokerClient.deliverReplyEvents, BrokerClient.publish, and BrokerClient.publishWithAck

destroy Method

destroy

void destroy() throws BrokerException

Destroys this BrokerClient object, including the event queue, the list of subscriptions, and all other state allocated for the client in the Broker.

Note: The local BrokerClient object is marked as disconnected, even if an exception is thrown.

See also: BrokerClient.BrokerClient, BrokerClient.disconnect, and BrokerClient.reconnect

disconnect Method

disconnect

void disconnect() throws BrokerException

Closes the connection between this Broker client and the Broker. The effect of this method depends on the life cycle of the Broker client, which is defined by the client group to which it belongs.

If the Broker client's life cycle is destroy-on-disconnect, the client state associated this BrokerClient is destroyed when it is disconnected. When the state is destroyed, any queued events and subscriptions are destroyed.

BrokerNoPermissionException The client does not have permission to publish all of the event types.

BrokerNullParameterException The dest_id or events parameter is null, or one or more of the events does not exist on the Broker.

BrokerOutOfRangeException The ack_type parameter does not contain one of the ACK_* values.







If the Broker client's life cycle is explicit-destroy, the Broker client's state on the Broker will persist until the Broker client is explicitly destroyed with the destroy method. In this case, calling the method BrokerClient.disconnect simply breaks the Broker client's connection to the Broker. After the Broker client is disconnected:

The associated client state continues to exist.

The Broker continues to queue messages for the Broker client.

The Broker client can resume processing events by reconnecting to the Broker.

Use the reconnect method to reconnect a disconnected Broker client.

Note: The local BrokerClient object is marked as disconnected even if an exception is thrown.

See also: BrokerClient.BrokerClient, BrokerClient.destroy, and BrokerClient.reconnect

dispatch Method

dispatch

static void dispatch( int msecs) throws BrokerException

Waits for an incoming event and dispatches it to a callback method. This method will return after an event is received and passed to a callback method or after the wait time, specified by msecs, has expired. If the wait time expires, this method throws a BrokerTimeOutException.

When using dispatch, you cannot invoke any of the following methods:

BrokerClient.mainLoop

BrokerClient.threadedCallbacks



msecs The number of milliseconds to wait for an event to process before timing out. If set to TIME_INFINITE, this method will wait indefinitely.



BrokerInterruptedException The interruptDispatch method was invoked.




See also: BrokerClient.getEvent, BrokerClient.getEvents, BrokerClient.interruptDispatch, BrokerClient.mainLoop, and BrokerClient.threadedCallbacks

does Method

doesSubscriptionExist

boolean doesSubscriptionExist( String event_type_name, String filter) throws BrokerException

Determines if a subscription with the specified event_type_name and filter exists on the Broker for this Broker client.

See also: BrokerClient.cancelSubscription and BrokerClient.newSubscription

end Methods

endAdapterTransaction

public int endAdapterTransaction( java.lang.String transaction_id, int mode, boolean want_ack) throws BrokerException

Publishes an Adapter::endTransaction event for the given transaction ID. The mode should be one of the TRANSACTION_MODE_* values. This method should be used in conjunction with the beginAdapterTransaction() method. If want_ack is false, this function returns 0. Otherwise, it returns the value of the tag used in the endAdapterTransaction event. In addition to the listed exceptions, any communications exception can be thrown.

BrokerOutOfRangeException The msecs is less than -1.

BrokerTimeoutException The wait time expired.


filter The filter string associated with the subscription. You can pass a null value if no filter was specified in the subscription.






endTransaction (deprecated)

int endTransaction( String transaction_id, int mode, boolean want_ack) throws BrokerException

Commits, rolls back, or sets a save point for a transaction by publishing an Adapter::endTransaction event for the given transaction identifier. Returns zero if want_ack is false and no acknowledgment will be sent. If want_ack is true, returns the tag value of the endTransaction event so that you can match it to the acknowledgment that will follow.

This method should be used in conjunction with the beginTransaction method.

See also: BrokerClient.beginTransaction



BrokerNoPermissionException The client does not have permission to publish the Adapter::endTransaction event type.

BrokerNullParameterException transaction_id is null.

BrokerOutOfRangeException mode is not a legal value.

transaction_id The identifier representing the transaction to be ended.

mode Identifies the transaction mode and should be one of the TRANSACTION_MODE_* values shown in “Constants” on page 204.

want_ack If true, indicates that an acknowledgment reply is requested and the tag value of this event is returned.



BrokerNoPermissionException The client does not have permission to publish Adapter::endTransaction.

BrokerOutOfRangeException The mode parameter contains an invalid value.



finalize Method

finalize

public void finalize()

Called by Java when you stop using this object. Performs a disconnect(). Do not rely upon this method to disconnect your clients.

Overrides:

finalize in class java.lang.Object

get Methods

getAccessLabel

short[] getAccessLabel() throws BrokerException

Returns the access label for this client. This label will be inserted in the publabel envelope field of every event the client publishes or delivers.

Access labels provide access control for event types which is independent of event type.

See also: setAutomaticControlLabel

getApiVersionNumber

public java.lang.String getApiVersionNumber()

Get the current API's version number. Returns the CURRENT_API_VERSION's constant values.

getApplicationName

String getApplicationName()

Returns the name of this BrokerClient object's client application.

See also: BrokerClient.BrokerClient and BrokerClient.reconnect


BrokerBadStateException The client has an owner, but the access label feature is not enabled.

BrokerBrokerFailureException The client has an owner, but an error occurred looking up the access label.


BrokerNoPermissionException The client does not have an owner so it cannot have an access label.



getBrokerHost

String getBrokerHost()

Returns the host name of the Broker for this client.

See also: BrokerClient.BrokerClient, BrokerClient.getBrokerPort, BrokerClient.getBrokerName, and BrokerClient.reconnect

getBrokerName

String getBrokerName() throws BrokerException

Returns the name of the Broker for this client. Any of the communications exceptions can be thrown if the default Broker was used in creating this Broker client.

See also: BrokerClient.BrokerClient, BrokerClient.getBrokerHost, BrokerClient.getBrokerPort, and BrokerClient.reconnect

getBrokerPort

int getBrokerPort()

Returns the port number of the Broker Server.

See also: BrokerClient.BrokerClient, BrokerClient.getBrokerHost, BrokerClient.getBrokerName, and BrokerClient.reconnect

getBrokerSSLCertificate

BrokerSSLCertificate getBrokerSSLCertificate() throws BrokerException

Returns the secure sockets layer (SSL) certificate of the Broker to which this client is connected.

See also: BrokerConnectionDescriptor.getSSLCertificate, BrokerConnectionDescriptor.getSSLEncryptionLevel, and BrokerConnectionDescriptor.getSSLCertificateFile




BrokerBadStateException The client is not using SSL.




getBrokerVersionNumber

int getBrokerVersionNumber()

Returns the version number of the Broker to which this client is connected. If the Broker's version number is newer than the client's version, the client's version number is returned.

getCanPublishNames

String[] getCanPublishNames() throws BrokerException

Returns an array of event type names containing the name of every event type that this BrokerClient can publish or deliver.

The events that a Broker client can publish are determined by the client group to which the Broker client belongs.

See also: BrokerClient.getCanPublishTypeDefs, BrokerClient.getCanSubscribeNames, and BrokerClient.getCanSubscribeTypeDefs

getCanPublishTypeDefs

BrokerTypeDef[] getCanPublishTypeDefs() throws BrokerException

Returns an array of event type definitions which this client can publish or deliver.

The events that a client can publish are determined by the client group to which the Broker client belongs.

See also: BrokerClient.getCanPublishNames, BrokerClient.getCanSubscribeNames, and BrokerClient.getCanSubscribeTypeDefs

getCanSubscribeNames

String[] getCanSubscribeNames() throws BrokerException

Returns an array of event type names to which this client can subscribe. These are also the event types that are permissible to be delivered to this BrokerClient.

The events to which a Broker client can subscribe are determined by the client group to which the Broker client belongs.







See also: BrokerClient.getCanPublishNames, BrokerClient.getCanPublishTypeDefs, and BrokerClient.getCanSubscribeTypeDefs

getCanSubscribeTypeDefs

BrokerTypeDef[] getCanSubscribeTypeDefs() throws BrokerException

Returns an array of event type definitions to which this client can subscribe. These are also the event types that are permissible to be delivered to this BrokerClient.

The events to which a Broker client can subscribe are determined by the client group to which the Broker client belongs.

See also: BrokerClient.getCanPublishNames, BrokerClient.getCanPublishTypeDefs, and BrokerClient.getCanSubscribeNames

getClientGroup

String getClientGroup()

Returns the name of the client group to which this BrokerClient belongs.


getClientId

String getClientId()

Returns the client identifier for this BrokerClient.


getClientInfoset

BrokerEvent getClientInfoset() throws BrokerException

Returns the infoset for this client, which is returned as a BrokerEvent for convenience.









See also: BrokerClient.setClientInfoset

getClientSSLEncryptionLevel

int getClientSSLEncryptionLevel() throws BrokerException

Returns one of the values listed in “Constants” on page 297 to indicate the secure sockets layer (SSL) encryption level available to this client.

See also: BrokerConnectionDescriptor.getSSLEncryptionLevel

getConnectionDescriptor

BrokerConnectionDescriptor getConnectionDescriptor()

Returns this Broker client's descriptor. If a null descriptor was passed when this Broker client was created, a descriptor which matches the default behavior is returned.

Note: This method cannot be used to get the actual Broker settings for a connection descriptor.

See also: BrokerClient.BrokerClient, BrokerClient.reconnect and BrokerConnectionDescriptor.BrokerConnectionDescriptor

getDefaultBrokerPort

static int getDefaultBrokerPort()

Returns the default port number for connecting to Brokers. The default port is used for non-SSL connections and has a value of 6849. The default port number is also used to calculate the SSL port numbers shown in “Connection Settings” on page 48.

See also: BrokerClient.getEvent and BrokerClient.setDefaultClientTimeout

getEvent

BrokerEvent getEvent( int msecs) throws BrokerException


BrokerBadStateException The client is not using SSL.




Acknowledges all previously retrieved events for this Broker client and then obtains a single event, if available.

Note: Use caution when simultaneously calling this method from the same client on multiple threads. An event received on one thread can be acknowledged by another thread. To ensure proper acknowledgement handling in this situation, use getEvents(int, long, int). For more information, see getEvents on page 238.

If no events are currently available, this method will wait for the number of milliseconds specified by msecs. If no events are received within the time-out interval, a BrokerTimeoutException is thrown. Any event that is obtained can be one for which this Broker client has registered a subscription, or it can be a delivered event.

Note: Before exiting, Broker clients with an explicit-destroy life cycle that are using BrokerClient.getEvent should explicitly acknowledge the receipt sequence number of the last event received using either BrokerClient.acknowledge or BrokerClient.acknowledgeThrough. Failure to do so will result in the last event being received again the next time you connect the Broker client.

Using this method on a client that has registered callbacks will temporarily disable the callback mechanism for this Broker client until this method returns.

Note: The Broker will delete all guaranteed events from the event queue after they are acknowledged. If you want to receive an event without acknowledging any previously retrieved events, use the getEvents method that takes a sequence number, and specify a sequence number of DO_NOT_ACK.

See also: BrokerClient.dispatch, BrokerClient.getEvents, BrokerClient.interruptGetEvents, BrokerClient.mainLoop, and BrokerClient.threadedCallbacks

msecs The number of milliseconds to wait for an event to process before timing out. If set to TIME_INFINITE, this method will wait indefinitely. If msecs is TIME_INFINITE (-1), it waits forever. If msecs is SYNCHRONOUS (-2), it returns immediately with either a single event, or an empty event if no events are available.


BrokerInterruptedException The interruptGetEvents method was invoked.


BrokerOutOfRangeException The msecs is less than -1.




getEvents

BrokerEvent[] getEvents( int max_events, int msecs) throws BrokerException

Acknowledges all previously retrieved events for this Broker client and then obtains one or more events, if available.

Note: Use caution when simultaneously calling this method from the same client on multiple threads. An event received on one thread can be acknowledged by another thread. To insure proper acknowledgement handling in this situation, use getEvents(int, long, int). For more information, see getEvents on page 238.

The number of events retrieved is not always predictable, due to network delays. This method returns as soon as it can with as many events as it can. If no events are currently available, this method will wait for the number of milliseconds specified by msecs. If no events are received within the time-out interval, a BrokerTimeoutException is thrown. Any events that are obtained can be ones for which this Broker client has registered a subscription or they can be delivered events.

Note: Before exiting, Broker clients with an explicit-destroy life cycle that are using BrokerClient.getEvents should explicitly acknowledge the receipt sequence number of the last event received using either BrokerClient.acknowledge or BrokerClient.acknowledgeThrough. Failure to do so will result in the last event being received again the next time you connect the Broker client.

Using this method on a client that has registered callback methods will temporarily disable the callback mechanism for this Broker client until this method returns.

Note: The Broker will delete all guaranteed events from the event queue after they are acknowledged. If you want to receive multiple events without acknowledging any previously retrieved events, use the getEvents method that takes a sequence number, and specify a sequence number of DO_NOT_ACK.

max_events The maximum number of events to receive. Up to 160 events can be received.

msecs The number of milliseconds to wait for an event to process before timing out. If set to TIME_INFINITE, this method will wait indefinitely. If msecs is TIME_INFINITE (-1), it waits forever. If msecs is SYNCHRONOUS (-2), it returns immediately with either events, or an array length of zero if no events are available.





See also: BrokerClient.dispatch, BrokerClient.getEvent, BrokerClient.interruptGetEvents, BrokerClient.mainLoop, and BrokerClient.threadedCallbacks

getEvents

BrokerEvent[] getEvents( int max_events, long seqn, int msecs) throws BrokerException

Acknowledges all the events received by this Broker client, up to the event specified by seqn and then obtains one or more events.

Note: Use caution when simultaneously calling this method from the same client on multiple threads. An event received on one thread can be acknowledged by another thread.

A BrokerTimeoutException is thrown if no events are received within the time-out interval. For more information on acknowledging events see “Using Sequence Numbers” on page 145.

The number of events retrieved is not always predictable, due to network delays. This method returns as soon as it can with as many events as it can.

The events that are returned can be those for which this Broker client has registered a subscription, they can be delivered events, or both.


BrokerOutOfRangeException The msecs is less than -1 or max_events is less than zero.


max_events The maximum number of events to receive. Up to 160 events can be received.

seqn The sequence number to acknowledge through. If set to 0, all previously retrieved events are acknowledged that were not explicitly acknowledged. If set to DO_NOT_ACK (-1), no previously retrieved events will be acknowledged.

msecs The number of milliseconds to wait for an event to process before timing out. If set to TIME_INFINITE, this method will wait indefinitely. If msecs is TIME_INFINITE (-1), it waits forever. If msecs is SYNCHRONOUS (-2), it returns immediately with either events, or an array length of zero if no events are available.




Using this method on a client that has registered callback methods will temporarily disable the callback mechanism for this Broker client until this method returns.

Note: The Broker will delete all guaranteed events from the event queue after they are acknowledged.

See also: BrokerClient.dispatch, BrokerClient.interruptGetEvents, BrokerClient.mainLoop, and BrokerClient.threadedCallbacks

getEventTypeDef

BrokerTypeDef getEventTypeDef( String event_type_name) throws BrokerException

Returns the event type definition for the specified event_type_name.

Note: An event type definition will not be returned if your client is not permitted to browse that event type. In most cases, event types which can be browsed are those which your client can publish or for which it can register subscriptions.

See also: BrokerClient.getEventTypeDefs, BrokerClient.getEventTypeNames, BrokerClient.getScopeNames, and BrokerEvent.getTypeDef




BrokerOutOfRangeException The msecs is less than -1, max_events is less than zero, or seqn is less than -1.


event_type_name The event type name whose event type definition is to be returned. See “Parameter Naming Rules” on page 419 for restrictions on event type names.



BrokerNoPermissionException The client does not have permission to publish or subscribe to the event type.





getEventTypeDefs

BrokerTypeDef[] getEventTypeDefs( String event_type_names[]) throws BrokerException

Returns the event type definitions for the specified event_type_names. Null values are returned for any of the event type names not known to the Broker or for which permission is denied.

Note: An event type definition will not be returned if your client is not permitted to browse that event type. In most cases, event types which can be browsed are those which your client can publish or for which it can register subscriptions.

See also: BrokerClient.getEventTypeDef, BrokerClient.getEventTypeNames, BrokerClient.getScopeNames, and BrokerEvent.getTypeDef

getEventTypeInfoset

BrokerEvent getEventTypeInfoset( String event_type_name, String infoset_name) throws BrokerException

Returns the infoset with the specified infoset_name for event_type_name. The infoset itself is returned as an event for convenience. The name of the infoset is stored as the name of the returned event.

event_type_names The event type names whose event type definitions are to be returned. See “Parameter Naming Rules” on page 419 for restrictions on event type names.



BrokerNullParameterException The event_type_names parameter or one of its entries is null.

event_type_name The event type name whose infoset is to be returned. See “Parameter Naming Rules” on page 419 for restrictions on event type names.

infoset_name The name of the infoset to be returned. See “Parameter Naming Rules” on page 419 for restrictions on infoset names.



See also: BrokerClient.getEventTypeInfosetNames, BrokerClient.getEventTypeNames, and BrokerClient.getEventTypeNames

getEventTypeInfosetNames

String[] getEventTypeInfosetNames( String event_type_name) throws BrokerException

Returns the names of all the infosets for event_type_name.

See also: BrokerClient.getEventTypeInfoset, BrokerClient.getEventTypeInfosetNames, and BrokerClient.getEventTypeNames



BrokerNoPermissionException The infoset is not named public and the client does not have permission to publish or subscribe to the event type.

BrokerNullParameterException The event_type_name or infoset_name parameter is null.


BrokerUnknownInfosetException The event type does not exist for the specified event type on the Broker.

event_type_name The event type name whose infoset names are to be returned. See “Parameter Naming Rules” on page 419 for restrictions on event type names.



BrokerNoPermissionException The client does not have permission to publish or subscribe to the event type.





getEventTypeInfosets

BrokerEvent[] getEventTypeInfosets( String event_type_name, String infoset_names[]) throws BrokerException

Returns the infosets with the specified infoset_names for event_type_name. The infosets are returned as an array of events for convenience. The name of each infoset is stored as the name of the returned event. Null values are returned for any of the infoset names not known to the Broker.

See also: BrokerClient.getEventTypeInfoset, BrokerClient.getEventTypeNames, and BrokerClient.getEventTypeNames

getEventTypeNames

String[] getEventTypeNames() throws BrokerException

Returns an array of fully qualified event type names known to the Broker to which this Broker client is connected.

Note: Only the names of the event types which your client is permitted to browse are returned. In most cases, this corresponds to the set of event types which your client can publish or for which it can register subscriptions.

event_type_name The event type name whose infoset is to be returned. See “Parameter Naming Rules” on page 419 for restrictions on event type names.

infoset_names The array of infoset names to be returned. If null, all infosets for the event type will be returned. See “Parameter Naming Rules” on page 419 for restrictions on infoset names.



BrokerNullParameterException The event_type_name or infoset_names parameter is null.

BrokerUnknownEventTypeException A single infoset is requested and it does not exist on the specified event type on the Broker.



See also: BrokerClient.getScopeNames

getEventTypeNames

String[] getEventTypeNames( String scope_name) throws BrokerException

Returns an array of the event type names with the specified scope_name from the Broker to which this BrokerClient is connected.

See also: BrokerClient.getScopeNames

getLastPublishSequenceNumber

Deprecated. This method has been deprecated for BrokerTransactionalClient. However, its use with BrokerClient is still supported.

long getLastPublishSequenceNumber() throws BrokerException

Returns the highest sequence number used by this Broker client for events that it published or delivered.

See also: BrokerClient.publish and BrokerEvent.setPublishSequenceNumber

getPlatformInfo

static String getPlatformInfo( String key) throws BrokerException



scope_name The event type scope whose names are to be returned.



BrokerNullParameterException The scope_name parameter is null.

BrokerUnknownEventTypeException The scope does not exist on the Broker.





Returns the value of the specified platform key.

See also: BrokerClient.getPlatformInfoKeys and BrokerClient.setPlatformInfo

getPlatformInfoKeys

static String[] getPlatformInfoKeys() throws BrokerException

Returns a list of platform keys. The following table shows the keys that are registered by the webMethods Broker Java API. Other, user-defined keys can also be set with the BrokerClient.setPlatformInfo method.

See also: BrokerClient.getPlatformInfo and BrokerClient.setPlatformInfo

getQueueLength

int getQueueLength() throws BrokerException

Returns the number of events currently in event queue for this Broker client.

Note: The length returned will include any unacknowledged events in the queue. This means the length might be greater than you expect if your Broker client has received events, but has not yet acknowledged them.

key The key of the value to be obtained. See BrokerClient.getPlatformInfoKeys for a list of values.


BrokerNullParameterException The key parameter is null.

BrokerUnknownKeyException The specified key does not exist.

Key Value

AdapterLang "Java"

AdapterLangVersion <current version>

OS The name of the operating system under which the caller is executing.

Hardware The name of the hardware platform on which the caller is executing.





See also: BrokerClient.clearQueue

getRetrievedStatus

Boolean getRetrievedStatus() throws BrokerException

Get the acknowledgment status of the event. Only use this method on events as a result of a browse request from a queue browser. Returns 'true' if the event is unacknowledged, otherwise returns false.

getRetrievedSessionID

int getRetrievedSessionID() throws BrokerException

Get the client session ID that retrieved this event. Only use this method on events that are a result of a browse request from a queue browser. Returns the session ID of the client session that retrieved this event.

getScopeNames

String[] getScopeNames() throws BrokerException

Returns a complete list of event type scope names from the Broker to which this BrokerClient is connected.

Note: Only the scope names of the event types which your client is permitted to browse are returned. In most cases, this corresponds to the scope names that contain event types which your client can publish or for which it can register subscriptions.

See also: BrokerClient.getEventTypeNames and BrokerEvent.getBaseTypeName

getStateShareLimit

int getStateShareLimit() throws BrokerException

Returns the maximum number of Broker clients that can share this Broker client's state. The client state includes the client's event queue and list of subscribed events. Returns NO_SHARE_LIMIT if there is no limit to the number of clients that can share this client's state.







See also: BrokerClient.setStateShareLimit and BrokerConnectionDescriptor.setSSLCertificate

getSubscriptions

BrokerSubscription[] getSubscriptions() throws BrokerException

Returns an array of open subscriptions for this Broker client.

See also: BrokerClient.cancelSubscription, BrokerClient.cancelSubscriptions, BrokerClient.newSubscription, and BrokerClient.newSubscriptions

getTerritoryName

String getTerritoryName() throws BrokerException

Returns the territory name of the Broker to which this client is connected. Any communications exception can be thrown.

See also: BrokerTypeDef.getTerritoryName

increment Method

incrementRedeliveryCount

void incrementRedeliveryCount( long seqn) throws BrokerException

Increments the redelivery counter (by one) for the event specified by seqn. For more information about using this method, see “Detecting Redelivered Events” on page 95.

In addition to the exceptions below, this method can throw any communications exception.





seqn The receipt sequence number of the event whose redelivery counter is to be incremented.



See also: BrokerConnectionDescriptor.getRedeliveryCountEnabled, BrokerConnectionDescriptor.getAutomaticRedeliveryCount, and BrokerEvent.getRedeliveryCount

interrupt Methods

interruptDispatch

static void interruptDispatch() throws BrokerException

Interrupts the current BrokerClient.dispatch call. If there is no dispatch in progress, the next call to BrokerClient.dispatch will be interrupted. The method is intended for use in multi-threaded client applications.

See also: BrokerClient.dispatch

interruptGetEvents

void interruptGetEvents() throws BrokerException

Interrupts the current BrokerClient.getEvent or BrokerClient.getEvents call.

See also: BrokerClient.getEvent and BrokerClient.getEvents

interruptCheckForEvents

void interruptCheckForEvents() throws BrokerException



BrokerInvalidOperationException Cannot increment the counter because the client is configured to use automatic incrementing.

BrokerOutOfRangeException seqn is a negative number.

BrokerInvalidSequenceNumberException seqn does not correspond to any event for this client.







Interrupts a thread on the current Broker client session that is blocked on a check for events call. If there is no such thread, the call simply returns. This operation is intended for use in multi-threaded clients. This function is safe for use in a signal handler.

See also: BrokerClient.checkForEvents and BrokerClient.cancelCheckForEvents

is Methods

isClientPending

boolean isClientPending() throws BrokerException

Returns true if any events are pending for this Broker client; otherwise false is returned. Events will be pending only if a previous call to prime or primeAllClients has been made.

See also: BrokerClient.isPending, BrokerClient.prime, and BrokerClient.primeAllClients

isConnected

boolean isConnected()

Returns true if this Broker client is currently connected to a Broker. If the Broker initiated a disconnect or if the Broker client has previously called disconnect or destroy, false is returned.

Note: This method does a passive check on this Broker client's connection to the Broker. No network access is performed to actually ensure that a connection actually exists.

isPending

static boolean isPending() throws BrokerException

Returns true if any events are pending for any Broker client; otherwise false is returned. Events will be pending only if a previous call to prime or primeAllClients has been made.









See also: BrokerClient.isClientPending, BrokerClient.prime, and BrokerClient.primeAllClients

main Method

mainLoop

static void mainLoop() throws BrokerException

Waits for an event to be received, then dispatches the event to the appropriate callback method, and then returns. It is logically equivalent to:

while(do_not_stop) { dispatch(TIME_INFINITE) };

See also: BrokerClient.dispatch, BrokerClient.getEvent, BrokerClient.getEvents, BrokerClient.stopMainLoop, and BrokerClient.threadedCallbacks

make Methods

makeSubId

int makeSubId()

Returns a subscription identifier that is unique for subscriptions generated for this Broker client during this execution. Use this method for destroy-on-disconnect clients or explicit-destroy clients that have not yet registered any event subscriptions. Otherwise, use the BrokerClient.makeUniqueSubId method.

Important! This method can create duplicate subscription identifiers for subscriptions registered before this Broker client session. Do not use this method with Broker clients that have subscriptions registered from previous sessions.

See also: BrokerClient.makeUniqueSubId, BrokerClient.newSubscription, and BrokerClient.newSubscriptions

makeTag

int makeTag()

Returns a unique value for use in an event's tag envelope field. The tag field is used in the request-reply model to associate reply events with their corresponding request event.

See also: BrokerEvent.getTag and BrokerEvent.setTag





makeTransactionId

String makeTransactionId() throws BrokerException

Generates a unique transaction identifier for use in transaction operations.

See also: BrokerClient.beginTransaction and BrokerClient.endTransaction

makeUniqueSubId

int makeUniqueSubId() throws BrokerException

Generates a unique subscription identifier. The first call to this method will query the Broker for any outstanding subscriptions so that this subscription identifier can be guaranteed to be unique. After calling this method once, subsequent calls to BrokerClient.makeSubId will return unique subscription identifiers.

See also: BrokerClient.makeSubId, BrokerClient.newSubscriptions, and BrokerClient.newSubscriptions

negative Methods

negativeAcknowledge

void negativeAcknowledge( long seqn) throws BrokerException

Negative acknowledges the receipt of a single event, specified by seqn, for this BrokerClient. By negative acknowledging an event, the BrokerClient asks the Broker to redeliver the event to it; usually BrokerClient receives the event the next time it asks the Broker for events. Only events whose receipt sequence number is greater than 0 can be negative acknowledged. Volatile events are always auto-acknowledged by the Broker and thus can never be negative acknowledged. In addition to the listed exceptions, any communications exception can be thrown.





seqn The event sequence number that is being negative acknowledged. The value must be greater than 0.



See also: BrokerClient.acknowledge, BrokerClient.acknowledgeThrough, and BrokerEvent.getReceiptSequenceNumber

negativeAcknowledge

void negativeAcknowledge( long seqn[]) throws BrokerException

Negative acknowledges the receipt of an array of events, specified by seqn, for this BrokerClient. By negative acknowledging an event, the BrokerClient asks the Broker to redeliver the event to it; usually BrokerClient receives the event the next time it asks the Broker for events. Only events whose receipt sequence number is greater than 0 can be negative acknowledged. Volatile events are always auto-acknowledged by the Broker and thus can never be negative acknowledged. In addition to the listed exceptions, any communications exception can be thrown.

See also: BrokerClient.acknowledge, BrokerClient.acknowledgeThrough, and BrokerEvent.getReceiptSequenceNumber



BrokerOutOfRangeException seqn is a negative number or 0.


BrokerInvalidSequenceNumberException seqn does not correspond to a received event.

seqn The event sequence number that is being negative acknowledged. The value must be greater than 0.



BrokerOutOfRangeException seqn is a negative number or 0.


BrokerInvalidSequenceNumberException seqn does not correspond to a received array of events.



new Methods

newOrReconnect

static BrokerClient newOrReconnect( String broker_host, String broker_name, String client_id, String client_group, String app_name, BrokerConnectionDescriptor desc) throws BrokerException

Attempts to create a new Broker client with an event queue and zero subscriptions. If a Broker client with the same client_id already exists, this client will be reconnected.

When finished with the Broker client, the application is responsible for calling BrokerClient.disconnect or BrokerClient.destroy.

broker_host The name of the host running the Broker that the new or reconnecting Broker client will use. Specified in the form <broker_host_name>:<port_number>. If the port number is omitted, the default port number will be used. For example: MyHost:12000

broker_name The name of the Broker. If set to null, the default Broker name is used. See “Parameter Naming Rules” on page 419 for restrictions on Broker names.

client_id The client identifier, identifying the client as the one that was previously disconnected. See “Parameter Naming Rules” on page 419.

client_group The name of the client group for the new Broker client. See “Parameter Naming Rules” on page 419 for restrictions on Broker names.


desc The connection descriptor to use for the client. If set to null, a default connection will be established which can be shared with other clients.



Note: When reconnecting, the client state sharing setting that was set when the Broker client was originally created will be used. Client state sharing can only be enabled or disabled when creating new Broker clients, regardless of the information in the BrokerClientDescriptor.

See also: BrokerClient.BrokerClient, BrokerClient.destroy, BrokerClient.disconnect, and BrokerClient.reconnect

newSubscription

void newSubscription( String event_type_name, String filter) throws BrokerException


BrokerClientContentionException Another Broker client is already using the specified client_id. For clients with shared state, the maximum number of reconnects has been exceeded.



BrokerInvalidClientIdException The client_id contains invalid characters.



BrokerNullParameterException The broker_host, client_id, client_group, or app_name parameter is null.


BrokerUnknownBrokerNameException The specified broker_name does not exist. If broker_name was null, then there is no default Broker.

BrokerUnknownClientGroupException The specified client_group does not exist on the Broker.

BrokerUnknownClientIdException The specified client_id does not exist on the Broker.

BrokerBasicAuthFailureException Basic authentication failed for the user.



Registers a subscription with the Broker with the specified event_type_name and filter. If filter is NULL, all events of the specified event type will be considered to match the subscription.

An asterisk can be added to the end of an event type name as a wildcard if you want to open a subscription for multiple event types. See “Using Wildcards” on page 92 for more information.

If the subscription has already been registered, calling this method will have no effect.

This method implicitly passes a subId field of zero; see newSubscription on page 255.

An exception will be thrown if the Broker client does not have permission to subscribe to the event type, based on its client group affiliation. See BrokerClient.canSubscribe and for more information.

See also: BrokerClient.cancelSubscription, BrokerClient.cancelSubscriptions, BrokerClient.doesSubscriptionExist, BrokerClient.getSubscriptions

newSubscription

void newSubscription( int sub_id, String event_type_name, String filter) throws BrokerException

event_type_name The event type name associated with subscription. See “Parameter Naming Rules” on page 419 for restrictions on event type names.

filter The filter string associated with the subscription. You can pass a null value if you do not want to use filtering.



BrokerInvalidSubscriptionException The filter string contains a parse error.

BrokerNoPermissionException The client does not have permission to subscribe to the event type.





Registers a subscription with the Broker with the specified sub_id, event_type_name and filter. If filter is NULL, all events of the specified event type will be considered to match the subscription.

An asterisk can be added to the end of an event type name as a wildcard if you want to open a subscription for multiple event types. See “Using Wildcards” on page 92 for more information.

An exception will be thrown if the Broker client does not have permission to subscribe to the event type, based on its client group affiliation. See BrokerClient.canSubscribe for more information.

Note: If the subscription has already been registered, invoking this method will have no effect. A subscription with a sub_id of 1 will not be replaced with a new subscription with a sub_id of 2 that is otherwise identical.

See also: BrokerClient.cancelSubscription, BrokerClient.cancelSubscriptions, BrokerClient.doesSubscriptionExist, BrokerClient.getSubscriptions, BrokerClient.makeSubId, and BrokerClient.makeUniqueSubId

sub_id The subscription identifier to be associated with this event subscription. If not specified, a default value of 0 will be used.


filter The filter string associated with the subscription. You can pass a null value if you do not want to use filtering.



BrokerInvalidSubscriptionException The filter string contains a parse error.

BrokerNoPermissionException The client does not have permission to subscribe to the event type.


BrokerOutOfRangeException The sub_id is less that zero.




newSubscription

void newSubscription( BrokerSubscription sub) throws BrokerException

Registers the subscription sub with the Broker. An exception will be thrown if the Broker client does not have permission to subscribe to the event type, based on its client group affiliation.

See BrokerClient.canSubscribe for more information.

Note: If the subscription has already been registered, invoking this method will have no effect.

See also: BrokerClient.cancelSubscription, BrokerClient.cancelSubscriptions, BrokerClient.doesSubscriptionExist, BrokerClient.getSubscriptions, and BrokerClient.newSubscription

newSubscriptions

void newSubscriptions( BrokerSubscription subs[]) throws BrokerException

sub The subscription to register for this Broker client, which specifies an event type name and a filter. See BrokerSubscription on page 382 for more information.



BrokerInvalidSubscriptionException The filter string in sub contains a parse error.

BrokerNoPermissionException The client does not have permission to subscribe to the event type specified by sub.

BrokerNullParameterException The sub.event_type_name parameter is null.

BrokerOutOfRangeException The sub.sub_id is less that zero.




Registers the array of subscriptions with the Broker. An exception will be thrown if the Broker client does not have permission to subscribe to one of the event types, based on its client group affiliation.

See BrokerClient.canSubscribe for more information.

If any of the subscriptions in subs have already been registered, those subscriptions will not be affected.

See also: BrokerClient.cancelSubscription, BrokerClient.cancelSubscriptions, BrokerClient.doesSubscriptionExist, BrokerClient.getSubscriptions, and BrokerClient.newSubscription

poll Method

poll

BrokerClientPoll[] poll( BrokerClientPoll[] polls, int msecs) throws BrokerException

subs An array of subscriptions to register for this Broker client. Each subscription specifies an event type name and a filter. See BrokerSubscription on page 382 for more information.



BrokerInvalidSubscriptionException One of the filter strings in subs contains a parse error.

BrokerNoPermissionException The client does not have permission to subscribe to the event type specified by sub.

BrokerNullParameterException The parameter subs is null or at least one of the subs[].event_type_name parameter is null.

BrokerOutOfRangeException One of the subs[].sub_id fields is less that zero.


polls The array of BrokerClientPoll objects that belong to the Broker clients for which this method will perform polling.



Returns an array of BrokerClientPoll objects whose polling conditions have been satisfied. You can use this method to construct a polling loop that monitors (polls) the queues of multiple clients.

To use this method, your application must generate an array containing a BrokerClientPoll object for each client whose queue you want to poll. It must also set the GET_EVENTS flag in each object, which tells the polling method to check for events in client queues.

When it executes, this method polls the set of clients in polls simultaneously. If the method discovers at least one event when it polls the clients' queues, it sets a flag in the clients' BrokerClientPoll objects that have events. If the method does not find an event in any client's queue, it continues to poll the queues until 1) events arrive, 2) the timeout period specified by msecs expires, or 3) the thread is interrupted, whichever occurs first.

After the polling methods finishes polling the entire set of clients represented in polls, it returns an array containing the BrokerClientPoll objects for those clients that have events in their queues (clients with empty queues are omitted from the returned array). By looping through this array and calling the getEvents method, your application can fetch the events for each of these clients.

Note: The poll method automatically calls prime(1) and primes the queue for each client that it puts in the BrokerClientPoll[] that it returns. If your application requires to get more than one event per getEvents call, be sure to prime the clients with a larger value before executing the BrokerClient.poll method and after calling the getEvents method.

For information about using the polling model to fetch events (including sample code), see “Getting Events using the poll Method” on page 101.

See also: BrokerClientPoll, BrokerClientPoll.GET_EVENTS, and BrokerClient.getEvent

prime Methods

prime

void prime() throws BrokerException

Sends a request for events for this Broker client, but does not block. Use this method for Broker clients that have no callback methods registered that intend to use the isPending or isClientPending methods.

Note: Calling this method before invoking BrokerClient.getEvents will cause only a single event to be returned even if multiple events are available in the event queue.

msecs The number of milliseconds this method waits for the condition specified in BrokerClientPoll to be met. To wait indefinitely (i.e. to specify an infinite timeout period), set msecs to -1.



See also: BrokerClient.isClientPending, BrokerClient.isPending, and BrokerClient.primeAllClients

primeAllClients

static void primeAllClients() throws BrokerException

Causes all Broker clients to send a request for events for this Broker client, but does not block. Use this method for Broker clients that have no callback methods registered that intend to use the isPending or isClientPending methods.

Note: Calling this method before invoking BrokerClient.getEvents will cause only a single event to be returned, even if multiple events are available in the event queue.

See also: BrokerClient.isClientPending, BrokerClient.isPending, and BrokerClient.prime

publish Methods

publish

void publish( BrokerEvent event) throws BrokerException

Sends event to the Broker to be published.

Note: An exception will be thrown if this Broker client does not have permission to publish the event type, based on its client group affiliation. See BrokerClient.canSubscribe for more information.



event The event to be published.





BrokerNullParameterException The event parameter is null.



See also: BrokerClient.deliver, BrokerClient.publish, and BrokerClient.publishWithAck

publish

void publish(BrokerEvent events[]) throws BrokerException

Sends the list of events to the Broker to be published.

Note: An exception will be thrown if this Broker client does not have permission to publish any of the event types, based on its client group affiliation. See BrokerClient.canSubscribe.

See also: BrokerClient.deliver, BrokerClient.publish, and BrokerClient.publishWithAck

publishRequestAndWait

BrokerEvent[] publishRequestAndWait( BrokerEvent event, int msecs) throws BrokerException


events An array of events to be published.



BrokerInvalidEventException One or more events does not match its type definition.

BrokerNoPermissionException The client does not have permission to publish one or more of the event types.

BrokerNullParameterException The events parameteror one of its elements is null.


event The request event to be published.





Publishes the single event and then waits until all replies are received. The last reply event is detected when an event is received with the envelope fields appSeqn and appLastSeqn being equal.

This method creates a value for the tag envelope field using makeTag method. This method blocks until all replies are received or until the requested time-out interval expires.

An exception will be thrown if the event is invalid, if this Broker client does not have permission to publish event, if event fails validation, or if a communications failure occurs.

See “Using Request-Reply” on page 107 for more information on using the request-reply model.

Note: You must register a general callback object, using the BrokerClient.registerCallback method, before invoking this method.

See also: BrokerClient.deliverRequestAndWait, BrokerClient.publish, and BrokerEvent.isLastReply

publishWithAck

void publishWithAck( BrokerEvent events[], int ack_type, long ack_seqn[]) throws BrokerException






BrokerNullParameterException The event parameteris null.





Sends the array of events to the Broker for publication with one of several options for acknowledging events already received by this client. Either all events or none will be published.

The setting of the ack_type and ack_seqn parameters will determine which events received by this client are to be acknowledged.

Note: An exception will be thrown if this Broker client does not have permission to publish any of the event types, based on its client group affiliation. See BrokerClient.canSubscribe.

ack_type Determines how the events will be acknowledged and must be set to one of the following:

ACK_NONE

ACK_AUTOMATIC

ACK_THROUGH

ACK_SELECTIVE

ack_seqn The array of sequence numbers to be acknowledged if ack_type is set to ACK_THROUGH or ACK_SELECTIVE.

ack_type ack_seqn Result

ACK_NONE Not applicable. No events are acknowledged.

ACK_AUTOMATIC Not applicable. All events received by the client are acknowledged.

ACK_THROUGH ack_seqn[0] contains the sequence number of the last event to be acknowledged. If set to 0, the behavior will be the same as ACK_AUTOMATIC

Acknowledges all events up to and including the sequence number specified by ack_seqn[0]. If the n_acks argument is zero, no events will be acknowledged.

ACK_SELECTIVE ack_seqn contains the sequence numbers of the specific events to be acknowledged.

Acknowledges the specific events whose sequence numbers are contained in ack_seqn. All sequence numbers must be greater than zero.



See also: BrokerClient.deliver, BrokerClient.deliverWithAck, and BrokerClient.publish

reconnect Method

reconnect

static BrokerClient reconnect( String broker_host, String broker_name, String client_id, BrokerConnectionDescriptor desc) throws BrokerException



The parameter ack_seqn contained an invalid sequence number. The events were not sent to the Broker.


BrokerInvalidEventException One or more events does not match its type definition.

BrokerNoPermissionException The client does not have permission to publish one or more of the event types.

BrokerNullParameterException The events parameteror one of its elements is null.

BrokerOutOfRangeException The ack_type parameter does not contain one of the ACK_* values.


broker_host The name of the host running the Broker that the Broker client will use. Specified in the form <broker_host_name>:<port_number>. If the port number is omitted, the default port number will be used. For example: MyHost:12000




Reconnects a previously disconnected client to a Broker so that the client can resume event processing. The client_id parameter identifies the Broker client as one you previously disconnected using BrokerClient.disconnect. When finished with the Broker client, the application is responsible for calling BrokerClient.disconnect or BrokerClient.destroy.

In addition to reconnecting previously disconnected Broker clients, this method can be used to connect a Broker client that wants to share client state with another Broker client.

Note: When reconnecting, the client state sharing that was set when the Broker client was originally created will be used, regardless of the settings in the BrokerConnectionDescriptor.

client_id The client identifier, identifying the client as the one that was previously disconnected. See “Using Broker Clients” on page 37 and “Parameter Naming Rules” on page 419 for more information.



BrokerClientContentionException Another Broker client is already using the specified client_id. For clients with shared state, the maximum number of reconnects has been exceeded.





BrokerNullParameterException The broker_host or client_id parameter is null.


BrokerUnknownBrokerNameException The specified broker_name does not exist. If broker_name was null, then there is no default Broker.

BrokerUnknownClientIdException The specified client_id does not exist on the Broker.



See also: BrokerClient.BrokerClient, BrokerClient.destroy, BrokerClient.disconnect, and BrokerClient.newOrReconnect

register Methods

registerCallback

void registerCallback( BrokerCallback obj, Object client_data) throws BrokerException

Registers a general callback for event types that do not match any specific callback that might have been registered. This general callback will only be called once for each event which is not handled by a specific callback.

When an event is received for client, the callback object obj will be used to process the event and will be passed client_data as a parameter. The content and use of client_data is determined by you the caller; it is not examined or used in any way by the webMethods Broker system.

Callbacks registered with this method are called non-specific callbacks because they can be invoked to handle any event. You can also use the registerCallbackForSubId method to register a specific callback object for a particular event subscription ID. Specific callback objects will take precedence over a non-specific callback object.

See also: BrokerCallback, BrokerClient.cancelCallbackForSubId, BrokerClient.cancelCallbackForTag, BrokerClient.cancelCallbacks, BrokerClient.registerCallbackForSubId, BrokerClient.registerCallbackForTag

registerCallbackForSubId

void registerCallbackForSubId( int sub_id, BrokerCallback obj, Object client_data) throws BrokerException

obj The general callback object being registered.

client_data Any data which you want to pass to the callback method when it is invoked.



BrokerNullParameterException The obj parameter is null.

sub_id The subscription identifier to match for this callback.



Registers a specific callback for event types that match the subscription identifier sub_id. When an event with the specified subscription ID is received for client, the callback object obj will be used to process that event and will be passed client_data as a parameter. The content and use of client_data is determined by you, the caller; it is not examined or used in any way by the webMethods Broker system.

Note: You must register a general callback object, using the BrokerClient.registerCallback method, before calling this method.

If a callback object has already been registered for sub_id, the previous callback registration will be replaced with the new registration.

Note: Use non-unique subscription IDs if you want multiple event types to be processed by the same callback object. If you want different event types to be processed by their own callback object, make sure that each of the Broker client's event subscriptions uses a unique subscription ID.

See also: BrokerClient.cancelCallbackForSubId, BrokerClient.cancelCallbacks, and BrokerClient.registerCallback

registerCallbackForTag

void registerCallbackForTag( int tag, boolean cancel_when_done, BrokerCallback obj, Object client_data) throws BrokerException

obj The specific callback object being registered.



BrokerBadStateException No general callback was registered prior to calling this method.



BrokerOutOfRangeException The sub_id parameter is less than zero.

tag The subscription identifier to match for this callback.



Registers a specific callback for event types with a tag field that matches tag.

If a callback has already been registered for the specified tag, it will be replaced with the new callback.

If you want to have different event types handled by their own unique callback, be sure that each request event uses a unique tag value.

Note: You must register a general callback using registerCallback before attempting to register a specific callback.

See also: BrokerClient.cancelCallbackForTag, BrokerClient.cancelCallbacks, and BrokerClient.registerCallback

registerConnectionCallback

void registerConnectionCallback( BrokerConnectionCallback obj, Object client_data) throws BrokerException

cancel_when_done If set to true, the callback will be automatically cancelled when BrokerEvent.isLastReply returns true.

obj The specific callback object being registered.



BrokerBadStateException No general callback was registered prior to calling this method.



obj The object whose handleConnectionChange method will be invoked when this client is disconnected or reconnected.

client_data Data that is to be passed to the handleConnectionChange callback method. This can be set to null.



Registers a connection callback object obj for this client. The callback object's handleConnectionChange method will be invoked if this client is disconnected or reconnected. If a callback object was already registered for this client, it will be replaced by the new callback object.

The callback method will be called with the connect_state parameter set to one of the CONNECT_STATE_* values, described in “Constants” on page 204, to indicate the current state of the client's connection.

You can un-register a previously registered callback object by invoking this method with a null obj parameter. See BrokerConnectionCallback on page 295 for more information on the BrokerConnectionCallback interface.

See also: BrokerConnectionCallback.handleConnectionChange

resend Method

resendUnacknowledgedEvents

resendUnacknowledgedEvents( long[] seqn) throws BrokerException

Resends a list of events that matches the given receipt seqn numbers for documents that you have already received from the Broker, but the documents have not yet been acknowledged. The call returns an array of BrokerEvents which have been resent. This method does not have a timeout factor, waits until it resends all the events with the given seqn numbers.

In addition to the listed exceptions, any communications exception can be thrown.



seqn A list of unacknowledged documents from the client queue that matches the given receipt of sequence numbers, seqn.


BrokerInterruptedException The interruptGetEvents is used to stop the call.


BrokerOutOfRangeException A duplicate/invalid seqn#.



set Methods

setAutomaticControlLabel

void setAutomaticControlLabel( boolean enabled) throws BrokerException

Enables or disables the automatic insertion of this Broker client's access label into the controlLabel envelope field of any event the client publishes or delivers.

See also: BrokerClient.getAccessLabel

setClientInfoset

void setClientInfoset( BrokerEvent infoset) throws BrokerException

Set the infoset for this client, which is specified as a BrokerEvent for convenience. Each client can store one infoset that can be used to contain information about its state or configuration.

See also: BrokerClient.getClientInfoset

setDefaultClientTimeout

static int setDefaultClientTimeout( int msecs)

enabled If set to true, the Broker client's access label will be automatically set in the controlLabel envelope field of any event the client publishes or delivers.



infoset The infoset to set for this client.



BrokerNullParameterException The infoset parameter is null.

msecs The number of milliseconds to wait for an event to process before timing out.



Sets the default time that a Broker client will wait for operations on the Broker before timing out. Returns the previous default value set for client timeout.

The default time-out is 30 seconds. Setting the time-out to a lower value in high-performance environments can provide your client applications with a more timely indication that a failure might have occurred.

If the time-out interval expires before a response is received, an exception will be thrown.

setPlatformInfo

static void setPlatformInfo( String key, String value) throws BrokerException

Sets the platform information key with the specified value. If the key is not known, it will be added along with its value.

See also: BrokerClient.getPlatformInfo and BrokerClient.getPlatformInfoKeys

setStateShareLimit

void setStateShareLimit( int limit) throws BrokerException

Sets the number of Broker clients that can share this Broker client's state. When two or more Broker clients share the same client state, they share the same event queue and event subscriptions.

If limit is less than the current number of clients sharing the state, all of the Broker clients are allowed to remain connected. However, no new clients will be allowed to share the client state until the number of clients drops below limit.

key The platform key whose value is being set.

value The value to be set for the key.


BrokerNoPermissionException The key parameter refers to a read-only item.

BrokerNullParameterException The key or value parameter is null.

limit The number of Broker clients that can share this Broker client's state. If set to NO_SHARE_LIMIT, an unlimited number of Broker clients can share this client's state.



See also: BrokerClient.getStateShareLimit

stop Method

stopMainLoop

static void stopMainLoop() throws BrokerException

Stops a previous invocation of BrokerClient.mainLoop. If there is no current invocation of mainLoop, the next invocation will be stopped.

This method is usually invoked from within a callback method or another thread.

See also: BrokerClient.mainLoop

threaded Method

threadedCallbacks

static void threadedCallbacks( boolean enabled) throws BrokerException

Enables or disables the use of threaded callbacks. Use this method in a multi-threaded, thread-safe client application to request that callbacks happen on an event thread instead of in calls to BrokerClient.dispatch or BrokerClient.mainLoop.

Throws BrokerBadStateException if another thread has already invoked BrokerClient.dispatch or BrokerClient.mainLoop, or if an attempt is made to set enabled to the state it is already in.

See also: BrokerClient.dispatch, BrokerClient.getEvent, BrokerClient.getEvents, and BrokerClient.mainLoop



BrokerNoPermissionException The client does not have a shared state.

BrokerOutOfRangeException The limit parameter is zero or less than -1.

enabled If set to true, enables the use of threaded callbacks. If set to false, disables the use of threaded callbacks.



to Method

toString

String toString()

Returns a string with information on this Broker client, suitable for display or printing.

BrokerClientPoll

class BrokerClientPoll extends java.lang.Object

This class is a container for information that the BrokerClient.poll method uses. To use the polling method, you must instantiate a BrokerClientPoll object for each client that will participate in the poll.

The BrokerClient.poll method is a particularly efficient way to receive incoming events for multiple Broker clients. Unlike the "get events" model, where multiple clients check their queues in a serial fashion and block for a period of time (thus preventing other clients operating in the same thread from accessing their queues) if their queue is empty, the BrokerClient.poll method dispatches a client to its queue only if there are events for it to retrieve. The result is a more efficient process that wastes fewer cycles on non-productive work (blocking).

The poll method also uses a single thread to manage the retrieval of events for multiple clients, which makes implementation easier than spawning an individual thread to for each client.

For information about the poll method, see “Getting Events using the poll Method” on page 101.

Constants

The BrokerClientPoll class has the following constants:



BrokerClientPoll constants

Constructors

BrokerClientPoll

BrokerClientPoll( BrokerClient client, int requested, java.lang.Object data) throws BrokerException

Creates an instance of BrokerClientPoll that client uses to monitor the Broker for the condition specified in requested. You use a BrokerClientPoll object in conjunction with the BrokerClient.poll method to notify a client that the specified condition exists on the Broker.

Note: BrokerClientPoll allows a client to monitor the Broker for the arrival of events in its queue.

You can use BrokerClientPoll with BrokerClient or BrokerTransactionalClient.

You cannot use the same BrokerClientPoll object or BrokerClientPoll[], with multiple threads simultaneously. Only a single thread can use a BrokerClientPoll object at a time.

For information about polling the Broker, see “Getting Events using the poll Method” on page 101.

Constant Description

int GET_EVENTS A bit-wise flag that enables polling for the presence of events in a client queue.

client The BrokerClient with which this BrokerClientPoll object will be used.

requested The condition for which client wants to poll. Must be set to: BrokerClientPoll.GET_EVENTS

This value specifies a request to poll for the presence of events in the queue belonging to client.

data Any data that you want to pass to client.

Possible Exception Meaning

BrokerNullParameterException client is null.

BrokerInvalidPollOperationException Value in requested is invalid.



See also: BrokerClient.poll, BrokerClientPoll.isready, and BrokerClientPoll.getBrokerClient

Methods

getBrokerClient

BrokerClient getBrokerClient()

Returns the BrokerClient associated with this BrokerClientPoll object. Typically used to obtain the clients associated with the BrokerClientPoll array that the BrokerClient.poll method returns.

For information about using this method, see “Getting Events using the poll Method” on page 101.

See also: BrokerClient.poll

getData

Object getData()

Returns the user data from this BrokerClientPoll object. Returns null if BrokerClientPoll does not contain user data.

See also: BrokerClientPoll.setData

getReady

int getReady()

Returns the operations that this BrokerClientPoll object indicates are ready for the client to act upon. Currently, this method returns only the following value:

BrokerClientPoll.GET_EVENTS

This value indicates that the BrokerClientPoll has detected the presence of events in the client's queue.

See also: BrokerClientPoll.GET_EVENTS, BrokerClientPoll.isReady, BrokerClientPoll.isRequested, and BrokerClientPoll.getRequested

getRequested

int getRequested()

Returns the operations for which this BrokerClientPoll is currently polling. Currently, this method returns only the following value:

BrokerClientPoll.GET_EVENTS

This value indicates that the object is polling for events in its client's queue.

See also: BrokerClientPoll.GET_EVENTS, BrokerClientPoll.isRequested, BrokerClientPoll.isReady, and BrokerClientPoll.getReady



isReady

boolean isReady( int operations) throws BrokerException

Returns true if the condition specified in operations has been satisfied for this BrokerClientPoll. False otherwise.

Currently, the only valid value for operations is BrokerClientPoll.GET_EVENTS, which returns true if the queue associated with this BrokerClientPoll object contains events.

See also: BrokerClientPoll.GET_EVENTS, BrokerClientPoll.getReady, BrokerClientPoll.isRequested, and BrokerClientPoll.getRequested

isRequested

boolean isRequested( int operations) throws BrokerException

Returns true if the condition specified in operations is enabled in this BrokerClientPoll. False otherwise.

Currently, the only valid value for operations is BrokerClientPoll.GET_EVENTS, which returns this BrokerClientPoll object is polling for events in the client's queue.

See also: BrokerClientPoll.GET_EVENTS, BrokerClientPoll.getRequested, BrokerClientPoll.isReady, and BrokerClientPoll.getReady

setData

Object setData(Object data)

operations The operation whose state you want to check. Must be set to: BrokerClientPoll.GET_EVENTS


BrokerInvalidPollOperationException Value specified in operations is invalid.

operations The operation whose state you want to check. Must be set to: BrokerClientPoll.GET_EVENTS


BrokerInvalidPollOperationException Value specified in operations is invalid.



Sets the user data field in this BrokerClientPoll with the specified object. Typically you would pass your user data to BrokerClientPoll when you instantiate it. However, you can use this method to set user data in this BrokerClientPoll object anytime after it has been instantiated. For example, you might use this method to write user data to this BrokerClientPoll when the polling operation is finished.

This method returns an object containing the user data previously in this BrokerClientPoll, if any, or null if BrokerClientPoll contained no user data.

See also: BrokerClientPoll.getData

BrokerClusterPublisherBrokerClusterPublisherextends java.lang.Object

Constructor

BrokerClusterPublisher

BrokerClientPoll( Java.lang.String broker_host, java.lang.String broker_name, java.lang.String client_id, java.lang.String client_group, java.lang.String app_name, BrokerConnectionDescriptor desc, BrokerConnectionDescriptor mon_desc) throws BrokerException

data The object containing user data. It can be null.


broker_name The name of the Broker. If set to null, the default Broker name is used.

client_id The client identifier.

client_group The name of the client group for the new client. Client groups are discussed in Administering webMethods Broker. See “Parameter Naming Rules” on page 419 for restrictions on Broker names.



Creates a cluster client. broker_name can be null to request the default broker. client_id cannot be null for creating cluster clients. desc can be null to create a default connection.

Methods

cancelConnectionCallback

void cancelConnectionCallback()



mon_desc The connection descriptor to use for the cluster monitor client. If set to null, a default connection will be established which can be shared with other clients.


BrokerClientExistsException If a client using the specified client ID already exists.

BrokerCommFailureException If problems occur establishing the connection.

BrokerHostNotFoundException If the specified host does not exist.

BrokerInvalidClientIdException The ID contains illegal characters.

BrokerInvalidNameException The app_name contains illegal characters.

BrokerNoPermissionException Permission to join the specified client group is denied.

BrokerNotRunningException Host exists but no broker is running on that host.

BrokerNullParameterException broker_host, client_group, or app_name are null.

BrokerSecurityException A secure connection is attempted but is rejected by the broker.

BrokerUnknownBrokerNameException The specified broker does not exist. If broker_name is null, this indicates that there is no default broker.

BrokerUnknownClientGroupException The specified client group does not exist on the broker.



Cancel the cluster client's connection callback, if any registered.

cancelSelectionCallback

void cancelSelectionCallback()

Cancel the cluster client's selection callback, if any registered.

canPublish

boolean canPublish( java.lang.String event_type_name) throws BrokerException

Returns true if this Broker client is allowed to publish the event_type_name; otherwise false is returned. A Broker client's publication permissions are determined by the client group to which it belongs. See Administering webMethods Broker for more information.


deliver

void deliver( java.lang.String dest_id, BrokerEvent event) throws BrokerException

Sends the event to the Broker client with a client identifier of dest_id. The Broker client that is to receive the delivered event is not required to have registered a subscription for the event type, but its client group must allow the client to receive the event type.

event_type_name The name of the event that this Broker client wants to publish.




BrokerSecurityException A secure connection is attempted but is rejected by the Broker.

BrokerUnknownEventNameException The event type does not exist on the Broker.

BrokerClusterPublisherIdException No Broker is available on the cluster pool.

dest_id The client identifier of the Broker client that is to receive the event.

event The BrokerEvent object to be delivered.





deliver

void deliver( java.lang.String dest_id, BrokerEvent[] event) throws BrokerException


Delivers the array of events to the Broker client with a client identifier of dest_id. Either all of the events or none of them are delivered. In addition to the listed exceptions, any communications exception can be thrown.






BrokerUnknownEventTypeException The event type for the event does not exist on the broker.


dest_id The client identifier of the Broker client that is to receive the events







deliverRequestAndWait

BrokerEvent[] deliverRequestAndWait( java.lang.String dest_id, BrokerEvent event, int msecs, boolean retry) throws BrokerException

Sends the event to the Broker for delivery to the client with the specified dest_id and then waits for all reply events to be received. The last reply event is detected when an event is received with the envelope fields appSeqn and appLastSeqn being equal.

This method creates a value for the tag envelope field using BrokerClient.makeTag method. This method blocks until the replies are received or until the time-out interval expires.

Note: You must register a general callback object, using the BrokerClient.registerCallback method, before invoking this method. Also note that an exception will not be thrown if the recipient, represented by dest_id, no longer exists.






dest_id The destination identifier of the Broker client to receive the event.

event The event to be delivered.


retry


BrokerBadStateException This is called from within a callback function




destroy

void destroy()

Destroys BrokerClusterPublisher. Destroys all the clients created on the territory Brokers as part of the cluster operations. It might throw any communications exception, but the local client object is marked as disconnected even if an exception is thrown.

disconnect

void disconnect()

Disconnects BrokerClusterPublisher. Deletes the local client object, but leaves the client state on the Broker for future reconnects.

Note: Destroy-on-disconnect clients destroy themselves when disconnect occurs; disconnect is identical to destroy in behavior for such clients.

Might throw any communications exception, but the local client object is marked as disconnected even if an exception is thrown.


BrokerInvalidClientIdException the destination ID includes invalid characters













excludeBroker

void excludeBroker( java.lang.String brokerName) throws BrokerException

Excludes the specified Broker from cluster operations. This requires a Broker name string as an argument. If the specified Broker is found in the current cluster publisher's Broker pool, it is removed from the pool. The specified Broker is considered for future cluster operations. If the Broker is not found in the cluster publisher's Broker pool, an exception is thrown.

getApplicationName

java.lang.String getApplicationName()

Gets the application name.

getCanPublishNames

java.lang.String[] getCanPublishNames() throws BrokerException

Returns an array of event type names containing the name of every event type that this client can publish or deliver.

The events that a Broker client can publish are determined by the client group to which the Broker client belongs


brokerName Name of the Broker to exclude from cluster operations.



BrokerClusterPublisherException The specified broker is not part of the cluster publisher operation or the last single broker client connection found on the client pool.






getClientGroup

public java.lang.String getClientGroup()

Returns the name of the client group to which this client belongs.

getClientId

public java.lang.String getClientId()

Returns the client identifier for this client.

getClusterPublisherInfo

public BrokerEvent getClusterPublisherInfo() throws BrokerException

Returns cluster publisher information. Information is set into a BrokerEvent as fields. The available values are:

getClusterPublisherStats

public BrokerEvent getClusterPublisherStats() throws BrokerException

Value Definition

client_id (unicode string) Client id

client_group (unicode string) Client Group

app_name (unicode string) Application Name

connection_callback (boolean) true, if a connection callback is registered; otherwise false.

selection_callback (boolean) true, if a selection callback is registered; otherwise false.

monitor_client (unicode string) Client id of the monitor client

brokers (structure array) An array of structures describing brokers used as part of cluster operations.

brokers[].broker_host (unicode string) Broker host name.

brokers[].broker_name (unicode string) Broker name.

brokers[].description (unicode string) Broker description.

brokers[].territory_name (unicode string) Broker's territory name

exclude_brokers (unicode string array) An array of strings listing the broker names that are excluded from the cluster operations.



Gets the cluster publisher statistics. Statistics are set into a BrokerEvent as fields. The available values are:

getLastUsed

java.lang.String getLastUsed() throws BrokerException

Returns the Broker name on which the last cluster operation was executed.

getMonitorClientId

public java.lang.String getMonitorClientId()

Returns the cluster monitor client's identifier.

Value Definition

now (date) Current time on the broker host.

numClients (int) Number of clients employed in cluster operations.

numExcludedBrokers (int) Number of brokers excluded from the cluster operations.

numEventsPublished (int) Number of events published using this publisher.

lastEventPublishTime (date) Time when last event was published by a member. Forever (zero date and time) if no events ever published.

numEventsDelivered (int) Number of events delivered using this cluster publisher.

lastEventDeliverTime (date) Time when last event was delivered using this cluster client. Forever (zero date and time) if no events ever delivered.

numEventsReceived (int) Number of events received as part of publish/deliverRequestAndWait operations on this cluster publisher.

lastEventReceiveTime (date) Time when last event was received on this cluster client. Forever (zero date and time) if no events ever received.

lastActivityOn (unicode string) Client id of the client on which the last operation was executed.



getTerritoryName

java.lang.String getTerritoryName() throws BrokerException

Returns the territory name of the client's Broker. Any communications exception can be thrown. Returns null if the client is not in a territory.

includeBroker

void includeBroker( java.lang.String brokerName) throws BrokerException

Includes the specified Broker for cluster operations. This call takes a Broker name string as an argument. If the specified Broker is found in the current cluster publisher's Broker pool, it is removed from the pool. The specified Broker is considered for future cluster operations. If the Broker is not found or not in the territory or already present in the cluster pool, appropriate exception is thrown.

isConnected

public boolean isConnected()

Checks to see if BrokerClusterPublisher is connected. This is a passive check, that is, it only tells if the BrokerClusterPublisher has been explicitly destroyed or disconnected, or if an error occurred on a previous call which indicated that the connection was closed. No active test of the connection is made. Returns true if the connection is valid and is still connected, or false if not.

localPublish

void localPublish( BrokerEvent[] event) throws BrokerException

Sends event to clients on the local Broker only. The event is given to the Broker to be given to all subscribing clients. In addition to the listed exceptions, any communications exception can be thrown.




brokerName Name of the Broker to include from cluster operations.

event The event to be published



localPublish

void localPublish( BrokerEvent[] events) throws BrokerException

Sends the list of events to the clients on the local Broker only. Gives an array of events to the Broker to be given to subscribing clients. Either all of the events or none of them are published. In addition to the listed exceptions, any communications exception can be thrown.



BrokerInvalidEventException One or more of the events do not match its type definition.

BrokerNoPermissionException Events are null, or one or more elements in the array is null.

BrokerNullParameterException Events are null, or one or more elements in the array is null.

BrokerUnknownEventTypeException The event type for one or more of the events do not exist on the Broker.

BrokerUnknownClusterPublisherException

No Broker is available on the cluster pool.












localPublishRequestAndWait

BrokerEvent[] localPublishRequestAndWait( BrokerEvent event, int msecs) throws BrokerException

Publish one request event and wait for replies. The event is given to the subscribers on the local broker only. Creates a value for the 'tag' envelope field using makeTag(). Blocks until the replies are received or until the requested timeout (TIME_INFINITE (-1) for infinite timeout) is reached. In addition to the listed exceptions, any communications exception can be thrown.

newOrReconnect

static BrokerClusterPublisher newOrReconnect( java.lang.String broker_host, java.lang.String broker_name, java.lang.String client_id, java.lang.String client_group, java.lang.String app_name, BrokerConnectionDescriptor desc, BrokerConnectionDescriptor mon_desc) throws BrokerException




BrokerBadStateException Called from within a callback function.










Attempts to create BrokerClusterPublisher. If the creation fails because the client already exists, then it reconnects to the client instead.



client_id The client identifier, identifying the client as the one that was previously disconnected. See “Client Identifiers” on page 42 and “Parameter Naming Rules” on page 419 for more information.

client_group The name of the client group for the new Broker client. Client groups are discussed in Administering webMethods Broker. See “Parameter Naming Rules” on page 419 for restrictions on Broker names.





BrokerClientContentionException The client ID is already in use by another client. For shared state clients, this means the maximum number of reconnects has been exceeded.





publish

void publish( BrokerEvent event) throws BrokerException

Sends event to the Broker to be published. The event is given to the Broker to be given to all subscribing clients. In addition to the listed exceptions, any communications exception can be thrown.







BrokerUnknownClientGroupException The specified client group does not exist on the broker.

BrokerUnknownClientIdException The specified client ID does not exist on the broker.











publish

void publish( BrokerEvent[] events) throws BrokerException

Sends the list of events to the Broker to be published. Either all of the events or none of them are published. In addition to the listed exceptions, any communications exception can be thrown.

publishRequestAndWait

BrokerEvent[] publishRequestAndWait( BrokerEvent event, int msecs, boolean retry) throws BrokerException



events The request events to be published.














Publishes the single event and then waits until all replies are received. The last reply event is detected when an event is received with the envelope fields appSeqn and appLastSeqn being equal.

This method creates a value for the tag envelope field using makeTag method. This method blocks until all replies are received or until the requested time-out interval expires.

An exception will be thrown if the event is invalid, if this Broker client does not have permission to publish event, if event fails validation, or if a communications failure occurs.

reconnect

static BrokerClusterPublisher reconnect( java.lang.String broker_host, java.lang.String broker_name, java.lang.String client_id, java.lang.String client_group, java.lang.String app_name, BrokerConnectionDescriptor desc, BrokerConnectionDescriptor mon_desc) throws BrokerException


BrokerBadStateException Called from within a callback function.






BrokerUnknownClusterClientException No Broker is available on the cluster pool.

broker_host The name of the host running the Broker that the Broker client will use. Specified in the form <broker_host_name>:<port_number>. If the port number is omitted, the default port number will be used. For example: MyHost:12000



Reconnects BrokerClusterPublisher. broker_name can be null to request the default Broker. The state sharing flag in the descriptor is ignored by this call. Whether or not the client shares state can only be set when making a new client. For BrokerClusterPublisher, only one active connection can be made to the Broker for a given client_id, and so an error will be returned on reconnect if the client_id is already in use on any of the territory Brokers.

.


client_id The client identifier, identifying the client as the one that was previously disconnected. See “Client Identifiers” on page 42 and “Parameter Naming Rules” on page 419 for more information.

client_group The name of the client group. Client groups are discussed in Administering webMethods Broker. See “Parameter Naming Rules” on page 419 for restrictions on Broker names.

app_name The name of the application that will reconnect the Broker client.










registerConnectionCallback

void registerConnectionCallback( BrokerCPConnectionCallback obj, java.lang.Object client_data)

Register a connection callback for this client. Calling this on a client which already has an existing callback will replace that callback. client_data can be null.

The callback method will be called with connect_state set to CONNECT_STATE_DISCONNECTED if the client is disconnected. It will be called with CONNECT_STATE_CONNECTED when the client connection is first established. It will again be called with CONNECT_STATE_RECONNECTED when the cluster client reestablishes client connection.

registerSelectionCallback

void registerClusterSelectionCallback( BrokerCPSelectionCallback obj, java.lang.Object client_data)





BrokerUnknownClientIdException The specified client ID does not exist on the broker.

obj The connection callback object being registered. It can be null to clear the callback.

client_data Data that is to be passed to the callback method. This can be set to null.



BrokerNullParameterException obj is null.




Registers a cluster client selection callback for this client. If a callback object was already registered for this client, it will be replaced by the new callback object. The callback method will be called whenever a cluster client needs must be selected from the cluster client pool. It will be called with an event or an array event to be published along with a BrokerInfo[] array containing a list of territory Brokers to which cluster client connection exists at present.

toString

java.lang.String toString()

Returns a string with the client information in a form suitable for human viewing. Returns null if the cluster client is not connected to broker.

Overrides: toString in class java.lang.Object

BrokerConnectionCallback

interface BrokerConnectionCallback

You use this interface to implement an object for handling connection notification for a Broker client. You provide an implementation for the handleConnectionChange method, which will be invoked when the Broker client is disconnected or reconnected from its Broker.

You register a BrokerConnectionCallback-derived object using the BrokerClient.registerConnectionCallback method, described on registerConnectionCallback on page 268.

Methods

handleConnectionChange

void handleConnectionChange( BrokerClient client, int connect_state, Object client_data);

obj The callback object being registered.This can be null to clear the callback.

client_data Data that is to be passed to the callback method. This can be set to null.

client The Broker client whose connection state has changed.



You provide an implementation of this callback method to handle client connection notification. You can implement this method to recreate any needed client state that might have been lost or to provide other functions, such as logging of error messages.

When the BrokerConnectionCallback object's callback method is invoked, that method's connect_state parameter will be set to one of the following CONNECT_STATE_* variables described in “Constants” on page 204.

See also: BrokerClient.registerConnectionCallback

BrokerConnectionDescriptor

class BrokerConnectionDescriptorextends java.lang.Object

This class provides methods that allow you to configure the connection between a Broker client and the Broker.

Connection Sharing. A BrokerClient object created with connection sharing set to true will allow its connection to the broker to be re-used by other BrokerClient objects in order to increase performance. When set to false, the network connection used by the client will never be shared.

Automatic Reconnect. A BrokerClient object created with automatic reconnect set to true will attempt to reconnect to the broker if at any time it finds that its connection to the broker has been lost. If its client does not exist, then a new one will get created. Explicitly calling disconnect() or destroy() on a client disables this feature.

Keep-Alive. A BrokerClient object created with the keep-alive options enabled will receive periodic "keep-alive" messages from the Broker to test whether the connection between the client and the Broker is operational. If the Broker does not receive a response to the keep-alive message in a specified period of time, the Broker forces a disconnect.

State Sharing. A BrokerClient object created with state sharing set to true will allow other BrokerClient objects to use reconnect to open sessions with the client's state on the broker. All BrokerClients which are sharing the client's state will affect one another. This feature should be used with care. A value of false, is the default, and causes the Broker to only allow one session to use the client's state at a time. This quality only applies to making a new client. It is completely ignored when reconnecting clients.

connect_state The client's connection state. This will be set to one of the CONNECT_STATE_* values, described in “Constants” on page 204.

client_data Any data that your callback method needs to perform its processing. This data is defined when you register your BrokerConnectionCallback object.



Shared Event Ordering. A BrokerClient object created with state sharing set to true and with enforced event order set to SHARED_ORDER_BY_PUBLISHER, will enforce that the events delivered to the clients are ordered so that no event from a publisher is processed until its preceding events are processed. If enforced event order is set to SHARED_ORDER_NONE, then no ordering is imposed on the events delivered to the clients. This feature should be used with care because it can cause a client's events to be processed out of order. A value of SHARED_ORDER_BY_PUBLISHER, is the default. This quality only applies to making a new client. It is completely ignored when reconnecting clients, or when creating clients which do not have state sharing enabled.

SSL Certificate Files. Broker SSL support requires a keystore file containing the public certificate/private key pair for the Broker Java client (as well as a keystore file for the Broker Server and another one for the Broker admin component), and a trust store file containing the trusted root for the certification authority, or CA.

SSL is enabled whenever the keystore file is not null. If the distinguished name is null, then the client connects anonymously (however, in that configuration, you cannot use ACLs, even if the Broker Server's SSL certificate is authenticated). If the keystore file is non-null, then the digital certificate stored in that file is used for authentication.

Access Label Hint. When using the access label adapter (ALA) feature, this allows a client to specify a hint string for looking up the client's access label. Access labels are looked up only when creating a client, so the hint is ignored when reconnecting.

Forced Reconnect. A BrokerClient object created with forced reconnect set to true can be forcefully reconnected to. This will reconnect to the client and possibly disconnect the existing connected session. Forced reconnect cannot be used in conjunction with shared state. A value of false is the default.

Redelivery Counting. A BrokerClient object created with redelivery counting set to true can detect instances of events that it has already received. When redelivery counting is enabled, the Broker will keep a counter that indicates the number of times it has sent an instance of an event to the Broker client. By testing the value of the counter, the Broker client can detect events that it has already received and process them in the appropriate way.

Username and Password. You can set user ID and password combinations to authenticate Broker's Java clients.

Constants

This class contains the following constants.

Return values Description

ENCRYPT_LEVEL_NO_ENCRYPTION Encryption support is not available.

ENCRYPT_LEVEL_US_DOMESTIC US domestic level encryption is supported.



Constructor


BrokerConnectionDescriptor();

Creates a BrokerConnectionDescriptor object with a default state that allows shared connections, but no sharing of client state. The Secure Sockets Layer (SSL) certificate file will be set to null.

See also: BrokerClient.BrokerClient, BrokerClient.newOrReconnect, and BrokerClient.reconnect


BrokerConnectionDescriptor( BrokerConnectionDescriptor desc);

Creates a BrokerConnectionDescriptor object with the same state as desc.

Methods

getAccessLabelHint

String getAccessLabelHint()

Returns the access label hint defined for this connection descriptor.

When using the access label feature, a client can specify a hint string to be used to look up the client's access label. The access label look-up occurs only when creating a client. The hint string will be ignored when reconnecting a Broker client.

See also: setAccessLabelHint

ENCRYPT_LEVEL_US_EXPORT This option specifies a lower level of encryption that in the past, was used for US export purposes.

USE_DEFAULT_DN This constant is no longer used.

In earlier releases, it was used with the setSSLCertificate on page 311 method to specify use of the default DN in a keystore file.

desc The BrokerConnectionDescriptor to be copied.

Return values Description



getAuthUserName

String getAuthUserName()

Returns the authentication username of Broker's Java client.

See also: BrokerConnectionDescriptor.setAuthInfo.

getAutomaticReconnect

boolean getAutomaticReconnect()

Returns true if the automatic re-connection feature for this descriptor is enabled. Otherwise, false is returned.

Note: You can disable the automatic re-connection feature by explicitly invoking BrokerClient.destroy or BrokerClient.disconnect.

If automatic re-connection is enabled, the Broker client associated with this descriptor will be automatically reconnected after the connection to the Broker is lost. See “Automatic Re-connection” on page 51 for a complete discussion of this feature.

See also: BrokerConnectionDescriptor.setAutomaticReconnect, BrokerClient.destroy, and BrokerClient.disconnect

getAutomaticRedeliveryCount

boolean getAutomaticRedeliveryCount()

Returns true if the redelivery counting feature is enabled in automatic mode (i.e. the Broker increments the redelivery counter); false otherwise.

For more information about using the redelivery counting feature, see “Detecting Redelivered Events” on page 95.

See also: getRedeliveryCountEnabled and setAutomaticRedeliveryCount

getConnectionShare

boolean getConnectionShare()

Returns true if this connection can be shared with other Broker clients; otherwise false is returned.

See also: BrokerConnectionDescriptor.setConnectionShare

getConnectionShareLimit

boolean getConnectionShareLimit()

Gets the maximum number of clients that can share the connection. The default value is Integer.MAX_VALUE.

See also: BrokerConnectionDescriptor.setConnectionShareLimit



getForcedReconnect

boolean getForcedReconnect()

Gets the forced_reconnect status of the descriptor.

See also: BrokerConnectionDescriptor.setForcedReconnect

getKeepAlivePeriod

int getKeepAlivePeriod()

Returns the keep-alive period, in seconds. This value indicates the length of time the Broker waits before issuing keep-alive messages on an idle connection.

The keep-alive period starts when the Broker receives any type of message from a client. If the Broker doesn't receive another message from that client before the keep-alive period elapses, it will send another keep-alive message to that client.

A return value of Integer.MAX_VALUE indicates that keep-alive messages are suppressed for this connection descriptor.

Note: Integer.MAX_VALUE does not indicate that the keep-alive feature is entirely disabled. It simply means that the Broker will not issue keep-alive messages to clients. Depending on the response time value (see getKeepAliveResponseTime, below) the Broker can still disconnect clients that are idle for a specified period of time. To determine whether the keep-alive feature is disabled entirely, check whether the keep-alive period and the keep-alive response values are both Integer.MAX_VALUE.

For more information about the keep-alive feature, see “Using Client Keep-Alive” on page 52.

See also: BrokerConnectionDescriptor.setKeepAlive, BrokerConnectionDescriptor.getKeepAliveResponseTime, and BrokerConnectionDescriptor.getKeepAliveRetryCount

getKeepAliveResponseTime

int getKeepAliveResponseTime()

Returns the keep-alive response time, in seconds. This value indicates the length of time the Broker waits before disconnecting a client whose connection appears to have dropped.

A return value of Integer.MAX_VALUE indicates that the response time is infinite.

Depending on the value of the keep-alive period (see getKeepAlivePeriod, above), the keep-alive response time can represent three different Broker behaviors:



When the keep-alive period is less than Integer.MAX_VALUE, the response time value represents the length of time the Broker waits for a client to respond to a keep-alive message. If the client does not respond in this period of time, the Broker either re-sends the message (if the retry limit has not been reached) or disconnects the client (if the retry limit has been reached).

When the keep-alive period is Integer.MAX_VALUE, and the response time is less than Integer.MAX_VALUE, the Broker automatically disconnects clients that have been idle longer than the keep-alive response time.

If both the keep-alive period and the keep-alive response time are Integer.MAX_VALUE, the keep-alive feature is disabled entirely.


See also: BrokerConnectionDescriptor.setKeepAlive, BrokerConnectionDescriptor.getKeepAlivePeriod, and BrokerConnectionDescriptor.getKeepAliveRetryCount

getKeepAliveRetryCount

int getKeepAliveRetryCount()

Returns the keep-alive retry value. The retry value specifies the maximum number of times the Broker will re-send a keep-alive message to an unresponsive client. If the Broker does not receive a response from a client after re-sending a keep-alive message the maximum number of times, it automatically disconnects that client.


See also: BrokerConnectionDescriptor.setKeepAlive, BrokerConnectionDescriptor.getKeepAlivePeriod, and BrokerConnectionDescriptor.getKeepAliveResponseTime

getRedeliveryCountEnabled

boolean getRedeliveryCountEnabled()

Returns true if the redelivery counting feature is enabled for this connection descriptor; false otherwise.

For more information about counting redeliveries, see “Detecting Redelivered Events” on page 95.

See also: BrokerConnectionDescriptor.getAutomaticRedeliveryCount and BrokerConnectionDescriptor.setRedeliveryCountEnabled

getSharedEventOrdering

String getSharedEventOrdering()



Returns a string containing the shared event ordering status for this descriptor. The value returned will be either BrokerConnectionDescriptor.SHARED_ORDER_BY_PUBLISHER or BrokerConnectionDescriptor.SHARED_ORDER_NONE. See “Event Processing with Shared Client State” on page 55 for more information.

See also: BrokerConnectionDescriptor.setSharedEventOrdering

getSSLCertificate

BrokerSSLCertificate getSSLCertificate( String keystore_file, String truststore_file, KeystoreType keystore_type, TruststoreType truststore_type, String password) throws BrokerException

Gets the Entrust SSL certificate.

Note: An overloaded version of this method from the previous release is included for backward compatibility support only, for SSL certificates saved in the Spyrus format.

keystore_file The name of the Broker Java client's keystore file.

truststore_file The name of the Broker Java client's trust store file.

keystore_type The file type of the keystore file for the Java client. Currently, the selection PKCS12 must be used. Other selections may be available in future releases.

truststore_type The file type of the trust store file for the Java client, which stores its SSL certificate's trusted roots. Currently, the selection JKS must be used. Other selections may be available in future releases.

password The keystore file's password.


BrokerFileNotFoundException The specified keystore_file or truststore_file cannot be found.

BrokerNoPermissionException The password is invalid or the keystore_file or truststore_file has an unrecognized format.

BrokerNullParameterException The password or the keystore_file or truststore_file parameter is null.



See also: BrokerConnectionDescriptor.getSSLDistinguishedName, BrokerConnectionDescriptor.getSSLCertificateDns, BrokerConnectionDescriptor.getSSLEncryptionLevel, BrokerConnectionDescriptor.getSSLCertificateFile, and BrokerClient.getBrokerSSLCertificate

getSSLCertificateDns

String[] getSSLCertificateDns( String certificate_file, String password) throws BrokerException

Returns an array of strings containing the DNs from the specified certificate_file (keystore file).

Note: This method is included for backward compatibility support only, for SSL certificates saved in the Spyrus format.

See also: BrokerConnectionDescriptor.getSSLDistinguishedName, BrokerConnectionDescriptor.getSSLCertificate, BrokerConnectionDescriptor.getSSLEncryptionLevel, BrokerConnectionDescriptor.getSSLCertificateFile, and BrokerConnectionDescriptor.getSSLRootDns

getSSLCertificateFile

String getSSLCertificateFile()

Returns the name of the SSL keystore file for the Broker clients created or reconnected using this descriptor.

BrokerSecurityException SSL support is not available.

certificate_file The name of the Broker Java client's keystore file.



BrokerFileNotFoundException The specified certificate_file cannot be found.

BrokerNoPermissionException The password is invalid or the certificate_file has an unrecognized format.

BrokerNullParameterException The password or the certificate_file parameter is null.






See also: BrokerConnectionDescriptor.getSSLDistinguishedName, BrokerConnectionDescriptor.setSSLCertificate, and BrokerClient.getBrokerSSLCertificate

getSSLCipherSuites

String getSSLCipherSuites()

Returns the name of the SSL cipher suites for the Broker clients created or reconnected using this descriptor.

See also: BrokerConnectionDescriptor.setSSLCipherSuites, BrokerConnectionDescriptor.setSSLCertificate, BrokerClient.getBrokerSSLCertificate, BrokerConnectionDescriptor.getSSLCertificateFile, and BrokerConnectionDescriptor.setSSLCertificateFile and

getSSLDistinguishedName

String getSSLDistinguishedName()

Returns the Broker Java client's SSL distinguished name (DN).


See also: BrokerConnectionDescriptor.getSSLCertificateFile and BrokerConnectionDescriptor.setSSLCertificate

getSSLEncrypted

Boolean getSSLEncrypted()

Returns the value of the SSL encryption flag for this descriptor. A return value of false indicates that the data traffic for Broker Java clients created or reconnected using this descriptor will not be encrypted. A return value of true indicates that the data traffic that occurs after SSL handshaking will be encrypted.

See also: BrokerConnectionDescriptor.setSSLEncrypted

getSSLEncryptionLevel

int getSSLEncryptionLevel()

Returns one of the encryption level constants, described in “Constants” on page 297, to indicate the SSL encryption level that is available for the calling application.




See also: BrokerConnectionDescriptor.getSSLCertificateFile, BrokerConnectionDescriptor.setSSLCertificate, and BrokerClient.getClientSSLEncryptionLevel

getSSLKeystore

String getSSLKeystore()

Returns the name of the client keystore file.

getSSLKeystoreType


Returns an enumeration for the file type of the keystore file. Currently, the only value is PKCS12.

getSSLKeystoreType


Returns an enumeration for the file type of the keystore file. Currently, the only value is PKCS12.

getSSLProvider

String getSSLProvider()

Returns the name of the SSL provider.

getSSLTruststoreType

TruststoreType getSSLTruststoreType()

Returns an enumeration for the file type of the truststore file. Currently, the only value is JKS.

getSSLRootDns

String[] getSSLRootDns( String certificate_file, String password) throws BrokerException

Returns an array of strings containing the DNs of the trusted roots from the specified certificate_file.

certificate_file The name of the trust store file containing the trusted roots.

password The trust store file's password.




See also: BrokerConnectionDescriptor.getSSLDistinguishedName, BrokerConnectionDescriptor.getSSLCertificate, BrokerConnectionDescriptor.getSSLCertificateDns, BrokerConnectionDescriptor.getSSLEncryptionLevel, and BrokerConnectionDescriptor.getSSLCertificateFile

getStateShare

boolean getStateShare()

Returns true if the client state associated with this connection descriptor can be shared with other Broker clients; otherwise false is returned.

See also: BrokerConnectionDescriptor.setConnectionShare, BrokerClient.getStateShareLimit, and BrokerClient.setStateShareLimit

setAccessLabelHint

void setAccessLabelHint(String hint)

Sets the access label hint for this descriptor.

When using the access label feature, a client can specify a hint string to be used to look up the client's access label. The access label look-up occurs only when creating a client. The hint string will be ignored when reconnecting a Broker client.

See also: getAccessLabelHint

setAuthInfo

void setAuthInfo (username, password)

Sets the username and password for basic authentication.


BrokerFileNotFoundException The specified certificate_file cannot be found.

BrokerNoPermissionException The password is invalid or the certificate_file has an unrecognized format.

BrokerNullParameterException password or certificate_file parameter is null.


hint The access label hint to be set for this descriptor. This can be set to null.



See also: BrokerConnectionDescriptor.getAuthPassword, and BrokerConnectionDescriptor.getAuthUserName.

setAutomaticReconnect

void setAutomaticReconnect(boolean reconnect)

Enables or disables the automatic re-connection feature for this descriptor, based on the setting of the reconnect parameter.

Note: You can disable the automatic re-connection feature by explicitly invoking BrokerClient.destroy or BrokerClient.disconnect.

If automatic re-connection is enabled, the Broker client associated with this descriptor will be automatically reconnected after the connection to the Broker is lost. See “Automatic Re-connection” on page 51 for a complete discussion of this feature.

See also: BrokerConnectionDescriptor.getAutomaticReconnect, BrokerClient.destroy, and BrokerClient.disconnect

setAutomaticRedeliveryCount

void setAutomaticRedeliveryCount(boolean on)

Sets the redelivery counter to automatic mode.

Note: This method by itself does not enable redelivery counting. To enable redelivery counting, use the setRedeliveryCountEnabled method.


See also: getAutomaticRedeliveryCount, getRedeliveryCountEnabled, and setRedeliveryCountEnabled.

setConnectionShare

void setConnectionShare( boolean shared)

reconnect If set to true, enables automatic re-connection behavior. If set to false, disables automatic re-connection behavior.

on If set to true, enables automatic redelivery counting. If set to false, disables automatic redelivery counting.



Enables or disables the sharing of this connection by multiple Broker clients.

See also: BrokerConnectionDescripton.getConnectionShare

setConnectionShareLimit

void setConnectionShareLimit( int limit)

Sets the maximum number of clients that may share the connection.

See also: BrokerConnectionDescripton.getConnectionShareLimit

setForcedReconnect

boolean setForcedReconnect()

Sets the forced_reconnect status of the descriptor.

See also: BrokerConnectionDescripton.getForcedReconnect

setKeepAlive

Enables, disables, and specifies the behavior of the keep-alive feature for this connection descriptor. The default is for the keep-alive feature to be disabled.

void setKeepAlive( int KeepAlivePeriod int MaxResponseTime int RetryCount) throws BrokerException

shared If set to true, enables the sharing of this connection with other Broker clients. If set to false, sharing is not allowed.

limit The maximum number of clients that may share the connection. It must be greater than or equal to 2. The default value is Integer.MAX_VALUE. This parameter is ignored if connection sharing is disabled.



Together, the values of MaxResponseTime, KeepAlivePeriod, and RetryCount can produce three different keep-alive modes: Normal, Listen Only, and Disable. Examples of each of the keep-alive modes are shown in the table below.

KeepAlivePeriod The time interval, in seconds, between keep-alive messages. This value determines the frequency with which the Broker issues keep-alive messages to idle clients.

Must be an integer between 0 and Integer.MAX_VALUE. Default is Integer.MAX_VALUE.

To suppress keep-alive messages, set KeepAlivePeriod to Integer.MAX_VALUE.

MaxResponseTime Time interval, in seconds, that the Broker waits before disconnecting a client whose connection appears to have dropped.

Must be an integer between 0 and Integer.MAX_VALUE. Default is Integer.MAX_VALUE.

To specify an infinite response time, set MaxResponseTime to Integer.MAX_VALUE.

RetryCount Number of times the Broker reissues a keep-alive message before disconnecting an unresponsive client.

Must be an integer between 1 and Integer.MAX_VALUE.

Keep-Alive values Normal mode Listen Only mode Disable mode

KeepAlivePeriod 60 Integer.MAX_VALUE*

Integer.MAX_VALUE*

MaxResponseTime 60 60 Integer.MAX_VALUE*

RetryCount 3 3 1*



* Required field for the specified keep-alive mode


See also: BrokerConnectionDescriptor.getKeepAlivePeriod, BrokerConnectionDescriptor.getKeepAliveResponseTime, and BrokerConnectionDescriptor.getKeepAliveRetryCount

setRedeliveryCountEnabled

void setRedeliveryCountEnabled(boolean on)

Enables or disables redelivery counting for this connection descriptor.


See also: getRedeliveryCountEnabled, getAutomaticRedeliveryCount, and setAutomaticRedeliveryCount

setSharedEventOrdering

void setSharedEventOrdering( String ordering) throws BrokerException

Example description for each keep-alive mode

The Broker sends a keep-alive message to the client every 60 seconds and expects a response within 60 seconds. If the Broker does not receive a response, it will retry up to 3 more times and then disconnect.

The Broker does not send a keep-alive message to the client, but it expects an activity from the client every Duration value (60 seconds). If the Broker does not receive an activity from the client, it will disconnect. The retry count is ignored.

The Broker disables the keep-alive feature.

on If set to true, enables redelivery counting behavior. If set to false, disables redelivery counting behavior.

Keep-Alive values Normal mode Listen Only mode Disable mode



Sets the shared event ordering status for the specified descriptor. See “Event Processing with Shared Client State” on page 55 for more information.

See also: BrokerConnectionDescriptor.getSharedEventOrdering

setSSLCertificate

BrokerSSLCertificate setSSLCertificate( String keystore_file, String truststore_file, KeystoreType keystore_type, TruststoreType truststore_type, String password) throws BrokerException

Sets the SSL keystore file and trust store file for this connection descriptor.

If the keystore_file is NULL, then SSL will be disabled for any Broker client created with the descriptor.

ordering The event ordering that you want, specified as either SHARED_ORDER_BY_PUBLISHER or SHARED_ORDER_NONE.


BrokerNullParameterException The ordering parameter is null.

BrokerOutOfRangeException The ordering parameter contains spaces or non-printable characters.

keystore_file The name of the Broker Java client's keystore file.

truststore_file The name of the Broker Java client's trust store file.

keystore_type The file type of the keystore file for the Java client. Currently, the selection PKCS12 must be used. Other selections may be available in future releases.

truststore_type The file type of the trust store file for the Java client, which stores its SSL certificate's trusted roots. Currently, the selection JKS must be used. Other selections may be available in future releases.




The Broker Server must be properly configured to use SSL. See Administering webMethods Broker for complete information.

setSSLCipherSuites

void setSSLCipherSuites ( String ssl_cipher_suites)

Sets the cipher suites for the SSL connection.

See also: BrokerConnectionDescriptor.getSSLCipherSuites

setSSLEncrypted

void setSSLEncrypted( boolean encrypted)

Sets the value of the SSL encryption flag for the descriptor desc. If encrypted is false, then data traffic not be encrypted. If set to true, all data traffic that occurs after SSL handshaking will be encrypted.

See also: BrokerConnectionDescriptor.getSSLEncrypted

setSSLProvider

void setSSLProvider( String ssl_provider)

Sets the name of the SSL provider.


BrokerFileNotFoundException The specified keystore_file or truststore_file cannot be found.

BrokerNoPermissionException The password is invalid or the keystore_file or truststore_file has an unrecognized format.

BrokerNullParameterException The password is null, but the keystore_file ortruststore_file is not null.


ssl_cipher_suites A string containing cipher suites to be used for the SSL connection.

encrypted If false, only SSL handshaking will be used. If true, all data traffic will be encrypted.

ssl_provider Name of the SSL provider.



See also: BrokerConnectionDescriptor.getSSLProvider

setSSLKeystore

string setSSLKeystore()

Sets the file path and name of the client keystore file.

setSSLKeystoreType

KeystoreType setSSLKeystoreType()

Sets an enumeration for the file type of the keystore file. Currently, the only value is PKCS12.

setSSLTruststore

string setSSLTruststore()

Sets the file path and name of the client trust store file.

setSSLTruststoreType

TruststoreType setSSLTruststoreType()

Sets an enumeration for the file type of the trust store file. Currently, the only value is JKS.

setStateShare

void setStateShare( boolean shared)

Enables or disables the sharing of the client state associated with this connection by multiple Broker clients.

See also: BrokerConnectionDescriptor.getStateShare,BrokerClient.getStateShareLimit, and BrokerClient.setStateShareLimit

toString

String toString()

Returns a string with information on this connection descriptor, suitable for display or printing.

shared If set to true, enables multiple Broker clients to share the client state associated with this connection. If set to false, sharing is not allowed.



BrokerCPConnectionCallbackpublic interface BrokerCPConnectionCallback

This class is implemented by any object which needs to be registered for cluster publisher connection callbacks. See “Broker Cluster Publisher Connection Notification” on page 181 for more information.

Method

handleConnectionChange

void handleConnectionChange( BrokerClusterPublisher bcp, int connect_state, java.lang.String conn_name, java.lang.Object client_data)

Implement this method to handle cluster publisher connection callbacks. State values are BrokerClient.CONNECT_STATE_*.

BrokerCPSelectionCallbackpublic interface BrokerCPSelectionCallback

This class is implemented by any object which implements a cluster publisher selection callback for cluster operations.

bcp The Broker cluster publisher whose connection state has changed.

connect_state The cluster publisher's connection state. This will be set to one of the CONNECT_STATE_* values described in “Constants” on page 204.

conn_name The fully qualified Broker name on which the change occurred.




Methods

chooseClusterClient

public int chooseClusterClient( BrokerClusterPublisher bcp, BrokerEvent event, BrokerInfo[] bi, java.lang.Object client_data)

Implement this method to select a cluster client to be used for a single publish operation. Returning an invalid index value (less than 0 or out of the bi array bounds would cause the BrokerClusterPublisher to resort to the default selection policy.

chooseClusterClient

public int chooseClusterClient( BrokerClusterPublisher bcp, BrokerEvent[] event, BrokerInfo[] bi, java.lang.Object client_data)

Implement this method to select a cluster client to be used for multi-publish operation. Returning an invalid index value (less than 0 or out of the bi array bounds would cause the BrokerClusterPublisher to resort to the default selection policy.

bcp The Broker cluster publisher to use for the operation.

event The event to publish.

bi The Broker data object that contains information on the available Brokers in the cluster publisher.


bcp The Broker cluster publisher to use for the operation.

event The array of events to publish.

bi An array of Broker data objects containing information on the available Brokers in the cluster publisher.




BrokerDate

class BrokerDate extends java.lang.Object

This class represents a date object that contains both time and date fields. Methods are provided to set and retrieve the date and time as well as to compare and translate date and time values.

Variables

Constructors

BrokerDate

BrokerDate()

This constructor creates an empty BrokerDate with the is_date_and_time variable set to false.

BrokerDate

BrokerDate( int year, int mo, int dy)

Name Description

int year Year value. (Must be less than 4096.)

int month Month value.

int day Day value.

int hour Hour value.

int min Minute value.

int sec Second value.

int msec Millisecond value.

boolean is_date_and_time Set to true if both date and time are represented. Set to false if only a date is represented.

year The four-digit year, such as 1996 (but less than 4096.)

mo The one or two-digit month.



This constructor creates a BrokerDate object with the date and time initialized. The is_date_and_time variable set to false.

BrokerDate

BrokerDate( int year, int mo, int dy, int hr, int m, int s, int ms)

This constructor creates a BrokerDate object with the date and time initialized. The is_date_and_time variable set to true.

BrokerDate

BrokerDate( java.util.Calendar calendar)

This constructor creates a BrokerDate object initialized from the specified Java calendar object. The is_date_and_time variable set to true.

BrokerDate

BrokerDate( java.util.Date date)

This constructor creates a BrokerDate object initialized from the specified Java date object. The is_date_and_time variable set to true.

BrokerDate

BrokerDate(BrokerDate date)

This constructor creates a BrokerDate object, copying the contents of date.

BrokerDate

BrokerDate( java.lang.String date_string) throws java.text.ParseException

dy The one or two-digit day.

calendar The Java calendar object to use.

date The Java Date object to use.

date The BrokerDate object to copy.

date_string The string containing the date to set in the newly created BrokerDate object.



This constructor creates a BrokerDate object, setting it with the date and time contained in date_string using the US English locale. If date_string contains a time specification, the object's is_date_and_time variable will be set to 1 (true). If only a date is specified, is_date_and_time will be set to 0 (false).

Some of the allowable date strings for the US English locale include:

"MM/dd/yyyy hh:mm:ss.SSS aaa"

"MM/dd/yyyy HH:mm:ss.SSS"

"MM/dd/yyyy hh:mm:ss aaa"

"MM/dd/yyyy HH:mm:ss"

"MM/dd/yy hh:mm:ss.SSS aaa"

"MM/dd/yy HH:mm:ss.SSS"

"MM/dd/yy hh:mm:ss aaa"

"MM/dd/yy HH:mm:ss"

"MM/dd/yyyy"

"MM/dd/yy"

See your JDK documentation for complete information on date string formats.

BrokerDate

BrokerDate( java.lang.String date_string, java.util.Locale locale) throws java.text.ParseException

This constructor creates a BrokerDate object, setting it with the date and time contained in the localized date_string. If date_string contains a time specification, the object's is_date_and_time variable will be set to 1 (true). If only a date is specified, is_date_and_time will be set to 0 (false).

See your JDK documentation for information on locale support and date string formats.


java.text.ParseException A parsing error was encountered in the date_string.


locale The locale to be used for the date string.



Methods

clear

void clear()

Clears the entire contents of this BrokerDate. The is_date_and_time variable set to false.

See also: BrokerDate.clearTime

clearTime

void clearTime()

Clears the time contents of this BrokerDate, but leaves the date portion intact. The is_date_and_time variable set to false.

See also: BrokerDate.clear

compareTo

int compareTo( BrokerDate d)

Compares this date to the specified BrokerDate and returns 0 if the dates are equal, -1 if this date is less than d, or 1 if this date is greater than d.

See also: BrokerDate.equals

equals

boolean equals( BrokerDate d)

Returns true if this date is equal to the specified BrokerDate.

See also: BrokerDate.compareTo

getJavaCalendar

Calendar getJavaCalendar() throws BrokerException


java.text.ParseException A parsing error was encountered in the date_string.

d The date to be compared to this object.

d The date to be compared to this object.



Returns a Java Calendar object for this BrokerDate object.

See also: BrokerDate.setJavaCalendar

getJavaDate

Date getJavaDate() throws BrokerException

Returns a java.util.Date object for this BrokerDate object. Millisecond accuracy is lost in the conversion.

See also: BrokerDate.setJavaDate

parseDate

static BrokerDate parseDate( java.lang.String date_string) throws IllegalArgumentException

Returns a BrokerDate object, set with the date contained in date_string. If date_string contains a time specification, the object's is_date_and_time variable will be set to 1 (true). If only a date is specified, is_date_and_time will be set to 0 (false).

Some of the allowable date string formats for the US English locale include:

"MM/dd/yyyy hh:mm:ss.SSS aaa"

"MM/dd/yyyy HH:mm:ss.SSS"

"MM/dd/yyyy hh:mm:ss aaa"

"MM/dd/yyyy HH:mm:ss"

"MM/dd/yy hh:mm:ss.SSS aaa"

"MM/dd/yy HH:mm:ss.SSS"

"MM/dd/yy hh:mm:ss aaa"

"MM/dd/yy HH:mm:ss"

"MM/dd/yyyy"


BrokerOutOfRangeException If the date in this object cannot be represented in a Java Calendar.


BrokerOutOfRangeException If the date in this object cannot be represented in a Java Date.




"MM/dd/yy"

See your JDK documentation for complete information on date string formats.

Invoking this method is equivalent to invoking:

parseLocalizedDate(date_string, java.util.Locale.US)

See also: BrokerDate.parseLocalizedDate

parseLocalizedDate

static BrokerDate parseLocalizedDate( java.lang.String date_string, java.util.Locale locale) throws IllegalArgumentException

Uses the specified locale to return a BrokerDate object, set with the date contained in date_string. If date_string contains a time specification, the object's is_date_and_time variable will be set to 1 (true). If only a date is specified, is_date_and_time will be set to 0 (false).

See your JDK documentation for complete information on locale support and date string formats.

See also: BrokerDate.parseDate

setDate

void setDate( int year, int mo, int dy)


IllegalArgumentException A parsing error was encountered in the date_string.




IllegalArgumentException A parsing error was encountered in the date_string.





Sets this BrokerDate object with the date specified. The is_date_and_time variable is not altered.

See also: BrokerDate.setDateTime and BrokerDate.setTime

setDateTime

void setDateTime( int year, int mo, int dy, int hr, int m, int s, int ms)

Sets this BrokerDate object with the date and time specified. The is_date_and_time variable set to true.

See also: BrokerDate.parseLocalizedDate and BrokerDate.setTime

setJavaCalendar

void setJavaCalendar( Calendar calendar)

Sets this BrokerDate object with the specified Java Calendar object. The is_date_and_time variable set to true.

See also: BrokerDate.getJavaCalendar





hr The hour in 24 hour format (0 through 23).

m The minute (0 through 60).

s The second 0 through 60).

ms The millisecond (0 through 999).

calendar The Java Calendar to be used to set this BrokerDate.



setJavaDate

void setJavaDate( java.util.Date date)

Sets this BrokerDate object with the specified Java Date object. The is_date_and_time variable set to true.

See also: BrokerDate.getJavaDate

setTime

void setDate( int hr, int m, int s, int ms)

Sets this BrokerDate object with the time specified. The is_date_and_time variable set to true. The year, month, and day members are not affected.

toLocalizedString

String toLocalizedString( java.util.Locale locale)

Using the default locale, returns a string with contents of this BrokerDate, suitable for display or printing. If the date is zero, an empty string will be returned.

Note: Milliseconds will not appear in the resulting string if they are zero.

toString

String toString()

Returns a string, using the US English locale, with the contents of this BrokerDate, suitable for display or printing. If the date is zero, an empty string will be returned.

Calling this function is equivalent to invoking:

date The Java Date to be used to set this BrokerDate.

hr The hour in 24 hour format (0 through 23).

m The minute (0 through 60).

s The second 0 through 60).

ms The millisecond (0 through 999).




toString(java.util.Locale.US)


toString

String toString( java.util.Locale locale)

Returns a localized string with contents of this BrokerDate, suitable for display or printing. If the date is zero, an empty string will be returned.


BrokerEvent

class BrokerEvent extends java.lang.Object implements java.io.Serializable

This interface represents an event that is published, delivered, or retrieved by a BrokerClient.

Every event contains envelope fields and data fields. Envelope fields are consistent for all event types and contain details about the event's sender, destination, and its transit. Envelope fields are described on “Envelope Fields” on page 80.

Event data fields contain the data that your client applications use to exchange information. Event data fields can contain a single value, a sequence of values with the same type, or a structure containing values of different types, or another, pre-defined, event.

This interface provides methods for setting and retrieving event fields.

Constants





BrokerEvent Constants

Constructors

BrokerEvent

BrokerEvent( BrokerClient client, java.lang.String event_type_name) throws BrokerException

Name Description

ENTIRE_SEQUENCE Used with the get<type>SeqField, getSequenceField, and getStructSeqFieldAsEvents methods to indicate that an entire sequence is to be retrieved. Used with the set<type>SeqField, setSequenceField, and setStructSeqFieldFromEvents methods to indicate that the size of the sequence should be reset.

AUTO_SIZE Used with the set<type>SeqField, setSequenceField, and setStructSeqFieldFromEvents methods to indicate that all elements in the source sequence should be used to set the destination sequence.

DEFAULT_PRIORITY Used with the getPriority and setPriority methods to indicate that the message priority has a default priority of 4. In a range of values from 0-9, a value of 0 is the lowest priority and 9 is the highest priority (expedited processing).

LOW_PRIORITY Used with the getPriority and setPriority methods to indicate that the lowest message priority is a value of 0, in a range of values from 0-9.

HIGH_PRIORITY Used with the getPriority and setPriority methods to indicate that the highest message priority is a value of 9 (expedited processing), in a range of values from 0-9.

client The Broker client with which this event is to be associated. If null, the event will not be type checked.



This constructor creates a BrokerEvent with the associated client context.

If client is not null, the names and types of the event's fields will be checked whenever they are set. If you attempt to set a field with a type that does not match the event type definition stored in the Broker, an exception will be thrown. This notifies you that you need to update your application to keep it synchronized with the latest event type definitions managed by the Broker.

For example, if your application adds a field named XX by calling BrokerEvent.setIntegerField and the field is defined to be of type long, an exception will be thrown.

Note: If client is set to null when a BrokerEvent is created, no type checking will occur when the event's fields are retrieved or set. However, the event's type name will be recorded in the event for later use. If you set a field in such an event and later want to set it to a different type, you must first use either the BrokerEvent.clear or BrokerEvent.clearField methods or an exception will be thrown.

BrokerEvent

BrokerEvent(BrokerEvent event) throws BrokerException

This constructor creates a BrokerEvent object and initializes it with the contents of event.

event_type_name A string containing the fully-qualified event type name for the event being created. See “Parameter Naming Rules” on page 419 for restrictions on event type names.


BrokerInvalidEventTypeNameException The event_type_name is invalid.

BrokerNoPermissionException The specified client does not have permission to publish or subscribe to the event type.


BrokerUnknownEventTypeException The client was specified but the event type is not found on the Broker.

event The event being copied.





BrokerEvent

Deprecated. This method has been deprecated for BrokerEvent as support for ReflectEvent has been dropped in API version 6.5.

BrokerEvent( BrokerClient client, java.lang.String event_type_name, Class storage_class) throws BrokerException

This constructor creates a BrokerEvent and stores the values for all of its fields in an object of the class specified by storage_class, instead of storing them in an internal, packed format. Under certain circumstances, this can offer increased performance.

Field type checking will still occur, even if client is null, but only those fields defined in the storage_class will be accessible.

Note: BrokerEvent objects created with this constructor perform best for locally created events that you do not intend to publish. If you plan to publish an event, using one of the regular BrokerEvent constructors will offer better performance.



storage_class The Java class to be instantiated and used to store the field values for the new event.


BrokerFieldNotFoundException A client was specified and a public data member in storage_class did not have a corresponding field with the same name in the event type with the specified event_type_name.

BrokerFieldTypeMismatchException A client was specified and the data type of a public data member in storage_class did not match the data type of the corresponding field the in the event type.

BrokerInvalidClassException The specified storage_class could not be instantiated using the Class.newInstance method.




See also: BrokerEvent.fromObject, BrokerEvent.getStorageObject, and BrokerEvent.toObject

BrokerEvent


BrokerEvent( BrokerClient client, java.lang.String event_type_name, Object storage_object) throws BrokerException

This constructor creates a BrokerEvent and stores the values for all of its fields in storage_object, instead of storing them in an internal, packed format. Under certain circumstances, this can offer increased performance.

Field type checking will still occur, even if client is null, but only those fields defined in the storage_object will be accessible.

Note: BrokerEvent objects created with this constructor perform best for locally created events that you do not intend to publish. If you plan to publish an event, using one of the regular BrokerEvent constructors will offer better performance.

BrokerNoPermissionException The specified client does not have permission to publish or subscribe to the event type or

BrokerNullParameterException The event_type_name or storage_class parameter is null.

BrokerUnknownEventTypeException A client was specified and the event type was not found on the Broker.



storage_object The object to be used to store the field values for the new event.




See also: BrokerEvent.fromObject, BrokerEvent.getStorageObject, and BrokerEvent.toObject

Methods

clear

void clear()

Clears all fields in this event so that the values can be rewritten.

See also: BrokerEvent.clearField

clearField

void clearField( string field_name) throws BrokerException

Clears the field in this event with the name field_name so that its value can be rewritten. If this event was created without a Broker client context, you must call this method before attempting to change the type of any event fields that have been set.


BrokerFieldNotFoundException A client was specified and a public data member in storage_object did not have a corresponding field with the same name in the event type with the specified event_type_name.

BrokerFieldTypeMismatchException A client was specified and the data type of a public data member in storage_class did not match the data type of the corresponding field the in the event type.


BrokerNoPermissionException The specified client does not have permission to publish or subscribe to the event type or

BrokerNullParameterException The event_type_name or storage_object parameter is null.

BrokerUnknownEventTypeException A client was specified and the event type was not found on the Broker.

field_name The name of the field to be cleared.



See also: BrokerEvent.clear

clearModificationFlag

void clearModificationFlag()

Clears this event's modification flag. After calling this method, subsequent calls to hasBeenModified will return false.

See also: BrokerEvent.hasBeenModified and BrokerEvent.setModificationFlag

fromBinData

static BrokerEvent fromBinData( BrokerClient client, byte data[]) throws BrokerException

Initializes this BrokerEvent using a byte array previously returned by the BrokerEvent.toString method. The client can be null if you want to create the event without type checking its contents.

See also: BrokerEvent.toString


BrokerFieldNotFoundException The specified field_name does not exist in the event.

BrokerFieldTypeMismatchException The field_name incorrectly accesses a type, such as using a subscript with a non-sequence field.

BrokerInvalidFieldNameException The field_name is invalid.

BrokerNullParameterException The field_name parameter is null.

client The client that is associated with this event.

data The binary data to use to create the event.


BrokerCorruptDataException The data parameter is not a valid BrokerEvent.


BrokerNullParameterException The data parameter is null.




fromObject


void fromObject( Object obj) throws BrokerException

Copies the values of all data members in obj which have the same name as a corresponding field in this event.

The obj object can define boolean data members with names in the format $<event_field_name\>, where <event_field_name\> corresponds to a field in this event. If any of these $-style variables is set to 0 (false), that event field willnot be set.

See also: BrokerEvent.toObject

get<type>Field

Methods such as BrokerEvent.getBooleanField and BrokerEvent.getShortField have the following general syntax:

<type> get<type>Field( java.lang.String field_name) throws BrokerException

obj The object whose data members are used to set the field values in this event.


BrokerFieldNotFoundException This BrokerEvent was created with a BrokerClient (so it is type-checked) and a public data member in obj does not have a corresponding field with the same name in this BrokerEvent.

BrokerFieldTypeMismatchException This BrokerEvent was created with a BrokerClient (so it is type-checked) and the data type of a public data member in obj does not match the data type of its corresponding field in this BrokerEvent.


field_name The name of the field to be returned. Note that with the nested field the field name must include all the structs that the event field is under. If the field name that has passed in the method does not have the struct information, BrokerFieldNotException will be thrown.



The following methods are provided to return the value associated with a specific field type.

If you get a field whose value was not set by the event's publisher, the field will contain one of the following default values:

Boolean values will have a value of false.

Integral data types (such as int, long, and short) will have a value of zero.

Floating point types will have a value of 0.0.

String types will have a contain a zero-length string

BrokerDate types will be empty.

See also: BrokerEvent.get<type>SeqField, BrokerEvent.getField, BrokerEvent.getSequenceField, BrokerEvent.getStructFieldAsEvent, and BrokerEvent.getStructSeqFieldAsEvents

Method Name Type Returned

getBooleanField boolean

getByteField byte

getCharField char

getDateField BrokerDate

getDoubleField double

getFloatField float

getIntegerField int

getLongField long

getShortField short

getStringField String

getUCCharField char

getUCStringField String


BrokerFieldNotFoundException The specified field_name does not exist in the event or an attempt was made to obtain the value of an envelope field that has not been set.






get<type>SeqField

Methods such as BrokerEvent.getBooleanSeqField and BrokerEvent.getShortSeqField have the following general syntax:

<type>[] get<type>SeqField( String field_name, int offset, int max_n) throws BrokerException

The following methods are provided to return the values associated with a specific sequence field type.

These methods return the values of sequence-type event fields, as listed above. Values of event fields can be requested in any order. If you get a sequence field whose value was not set by the event's publisher, a zero-length sequence will be returned.

To get a sequence of structures, use the getStructSeqFieldAsEvents. To get values of non-sequence type event fields, use one of the get<type>Field methods.

field_name The name of the field to be returned. Note that field_name can directly identify any field in the event, no matter how deeply nested that field might be.

offset The number of elements to skip from the beginning of the sequence.

max_n The number of elements requested. If set to ENTIRE_SEQUENCE, all elements are requested.

Method Name Type Returned

getBooleanSeqField boolean[]

getByteSeqField byte[]

getCharSeqField char[]

getDateSeqField BrokerDate[]

getDoubleSeqField double[]

getFloatSeqField float[]

getIntegerSeqField int[]

getLongSeqField long[]

getShortSeqField short[]

getStringSeqField String[]

getUCCharSeqField char[]

getUCStringSeqField String[]



A sequence is a series of values with the same type, similar in concept to an array. Sequence-type event fields are created using one of the set<type>SeqField methods. You can create sequences of more than one dimension by building sequences of sequences.

To get all sequence values in one call, set max_n = -1 and offset = 0.

You can limit the number of sequence values returned by specifying a max_n\>0 and offset=0 on the first call. For subsequent calls, set offset to the number of elements already processed, so that the elements already retrieved can be skipped.

For example, if there are 75 strings in a sequence, and you want to handle no more than 50 on each method call:

On the first call to getStringSeqField, pass:

max_n=50, offset=0, n=50 (returned)

On the second call to getStringSeqField, pass:

max_n=50, offset=50(already processed), n=25(returned)

On return, every method returns an array; for example:

The getCharSeqField method returns a char array.

The getStringSeqField method returns a String array.

See also: BrokerEvent.get<type>Field, BrokerEvent.getField, BrokerEvent.getSequenceField, BrokerEvent.getStructFieldAsEvent, and BrokerEvent.getStructSeqFieldAsEvents

getBaseTypeName

String getBaseTypeName()

Returns the event type name of this object without the scope qualification.

See also: BrokerEvent.getScopeTypeName and BrokerEvent.getTypeName






BrokerOutOfRangeException The offset is less than zero, or greater that the sequence size, or max_n is less than zero.



getBooleanField

See BrokerEvent.get<type>Field.

getBooleanSeqField

See BrokerEvent.get<type>SeqField.

getByteField


getByteSeqField


getCharField


getCharSeqField


getClient

BrokerClient getClient()

Returns the Broker client associated with this event. If this event was created without a Broker client context, a null value is returned.

getDateField


getDateSeqField


getDoubleField


getDoubleSeqField


getEventId

long getEventId()



Returns the event ID, as set by the Broker, for this event.

Returns a value of zero under any one of the following conditions:

This event was created locally and was not received from the Broker.

This event was published by a client using a pre-3.0 release of ActiveWorks.

getField

BrokerField getField( String field_name) throws BrokerException

Returns the field from this event with the specified field_name. This is a generic access method and it cannot be used to retrieve sequence fields.

See also: BrokerEvent.get<type>Field, BrokerEvent.get<type>SeqField, BrokerEvent.getSequenceField, BrokerEvent.getStructFieldAsEvent, and BrokerEvent.getStructSeqFieldAsEvents

getFieldNames

String[] getFieldNames( String field_name) throws BrokerException

Returns an array of field names in this event or a list of field names within a structure field. If field_name is null, a list of event fields is returned.

field_name The name of the field to be returned.


BrokerFieldNotFoundException Specified field_name does not exist in the event or an attempt was made to obtain the value of an envelope field that has not been set.



BrokerInvalidTypeException The field is a sequence.


field_name The name of the structure field whose contained field names are to be returned. See “Parameter Naming Rules” on page 419 for restrictions on event field names.



See also: BrokerEvent.getFieldType

getFieldType

short getFieldType( String field_name) throws BrokerException

Returns the type of the field named field_name in this event. The type returned is one of the following variables, declared in BrokerTypeDef.

FIELD_TYPE_BYTE FIELD_TYPE_SHORT FIELD_TYPE_INT FIELD_TYPE_LONG FIELD_TYPE_FLOAT FIELD_TYPE_DOUBLE FIELD_TYPE_BOOLEAN FIELD_TYPE_DATE FIELD_TYPE_CHAR FIELD_TYPE_STRING FIELD_TYPE_UNICODE_CHAR FIELD_TYPE_UNICODE_STRING FIELD_TYPE_SEQUENCE FIELD_TYPE_STRUCT FIELD_TYPE_UNKNOWN

If you request type information for a sequence field named mySeq, this method will return FIELD_TYPE_SEQUENCE. If you want to obtain the type of the elements contained in mySeq, you can use this method with the field name mySeq[].


BrokerFieldNotFoundException Specified field_name does not exist in the event.




field_name The name of the field whose type is to be returned. See “Parameter Naming Rules” on page 419 for restrictions on event field names.


BrokerFieldNotFoundException Specified field_name does not exist in the event.



See also: BrokerEvent.getField and BrokerEvent

getFloatField


getFloatSeqField


getIntegerField


getIntegerSeqField


getLongField


getLongSeqField


getPriority

getPriority()

Returns the message priority of values from 0-9, where 0 is the lowest priority and 9 is the highest priority (expedited processing). The default is 4. For more information about how to use priority ordering, see “Priority Ordering for Broker Queues” on page 57.

See also: BrokerEvent.setPriority

getPublishSequenceNumber


long getPublishSequenceNumber()







Returns the publish sequence number from this event.

Note: The BrokerEvent.getPublishSequenceNumber method can only be used for events created by your client application that it intends to publish. It cannot be used to obtain a sequence number from a received event. See “Read-only Envelope Fields” on page 82.

See also: BrokerClient.publish and BrokerEvent.setPublishSequenceNumber

getReceiptSequenceNumber

long getReceiptSequenceNumber()

Returns the receipt sequence number from this event. Zero is returned if the event was created locally or if the event is a volatile event that was received from the Broker.

See also: BrokerEvent.setPublishSequenceNumber

getScopeTypeName

String getScopeTypeName()

Returns the scope specified for this event type.

See also: BrokerEvent.getBaseTypeName and BrokerEvent.getTypeName

getSequenceField

BrokerField getSequenceField( String field_name, int offset, int max_n) throws BrokerException

Returns the sequence field from this event with the specified field_name. This is a generic access method. For information on how to use offset, max_n, and value; see BrokerEvent.get<type>SeqField method. For more information, see get<type>SeqField on page 333.

If you get a sequence field whose value was not set by the event's publisher, a zero-length sequence will be returned.

field_name The name of the sequence field to be returned.

offset Number of elements to skip from the beginning of the sequence.

max_n Number of elements requested this call. If set to ENTIRE_SEQUENCE, all elements will be obtained.



See also: BrokerEvent.get<type>Field, BrokerEvent.get<type>SeqField, BrokerEvent.getField, BrokerEvent.getSequenceFieldSize, BrokerEvent.getStructFieldAsEvent, and BrokerEvent.getStructSeqFieldAsEvents

getSequenceFieldSize

int getSequenceFieldSize( String field_name) throws BrokerException

Returns the number of elements in the sequence specified by field_name.

See also: BrokerEvent.get<type>SeqField, BrokerEvent.getSequenceField, and BrokerEvent.getStructSeqFieldAsEvents





BrokerInvalidTypeException The field is a sequence of sequences.



field_name The name of the sequence field whose size is to be returned.








getShortField


getShortSeqField


getStorageObject


Object getStorageObject()

Returns the storage object being used by this BrokerEvent. If this event was not created using the constructors that accept an object or a Java class, null will be returned.

Note: If the event was created with an object instance, that instance will be returned. If this event was created with a Java class, an instance of that class will be created and returned.

See also: BrokerEvent.BrokerEvent

getStringField


getStringSeqField


getStructFieldAsEvent

BrokerEvent getStructFieldAsEvent( String field_name) throws BrokerException

Returns the structure field with the specified field_name from this event. To make processing more convenient, the structure field is returned as an event. Each event field corresponds to a field in the structure. Use the appropriate get<type>Field or get<type>SeqField methods to obtain the value of the fields within the structure.

If you get a structure field whose value was not set by the event's publisher, a structure will be returned set with all the appropriate default values.

field_name The name of the struct field to be returned. You can set this to null if you want to obtain the top level of the event.



Note: Because the event returned is not associated with a Broker client, it is not type checked.

See also: BrokerEvent.get<type>Field, BrokerEvent.getField, BrokerEvent.getStructSeqFieldAsEvents, and BrokerEvent.setStructFieldFromEvent

getStructSeqFieldAsEvents

BrokerEvent[] getStructSeqFieldAsEvents( String field_name, int offset, int max_n) throws BrokerException

Returns an array of events, each representing a structure in the sequence contained in this event. For information on how to use offset and max_n, see BrokerEvent.get<type>SeqField.

If you get a structure field whose value was not set by the event's publisher, a zero-length sequence will be returned.

Note: Because the returned events are not associated with a Broker client, they will not be type checked.


BrokerFieldNotFoundException Specified field_name does not exist in the event or an attempt was made to obtain the value of an envelope field that has not been set.



field_name The name of the sequence field to be returned.

offset Number of elements to skip from the beginning of the sequence.

max_n Number of elements requested this call. If set to ENTIRE_SEQUENCE, all elements will be obtained.



See also: BrokerEvent.get<type>SeqField, BrokerEvent.getSequenceField, BrokerEvent.getStructFieldAsEvent, and BrokerEvent.setStructSeqFieldFromEvents

getSubscriptionIds

int[] getSubscriptionIds()

Returns the subscription identifiers associated with this event. The following return values are possible:

A null value indicates that this event was created locally.

A zero length array indicates this event was delivered by the Broker. Delivered events are not matched to subscriptions.

See also: BrokerClient.cancelSubscriptions, BrokerClient.newSubscriptions, and BrokerClient.newSubscriptions

getRedeliveryCount

int getRedeliveryCount()

Returns the value of the redelivery counter for this event. A value of 0 indicates that the client is receiving this event for the first time. Values greater than 0 indicate that the client has received the event before and specifies the number of times the event has been received (e.g., a value of 1, indicates that the client has received the event once before, a value of 2 indicates that the client has received the event twice before, and so forth).

A value of -1 indicates that the redelivery counting feature is not enabled for this event.

For additional information about counting redelivered events, see “Detecting Redelivered Events” on page 95.









See also: BrokerConnectionDescriptor.getRedeliveryCountEnabled, BrokerConnectionDescriptor.getAutomaticRedeliveryCount, BrokerConnectionDescriptor.setRedeliveryCountEnabled, and BrokerClient.incrementRedeliveryCount

getTag

int getTag() throws BrokerException

Returns the tag envelope field from this event. This equivalent to the following call:

getIntegerField("_env.tag")

See also: BrokerEvent.setTag and BrokerClient.makeTag

getTypeDef

BrokerTypeDef getTypeDef() throws BrokerException

Returns the event type definition for this event. A null value is returned if this event was not created with a Broker client context.

See also: BrokerClient.getCanPublishTypeDefs, BrokerClient.getCanSubscribeTypeDefs, BrokerClient.getEventTypeDef, and BrokerEvent.getEventTypeDefs

getTypeName

String getTypeName()

Returns the fully qualified event type name of this event.

See also: BrokerClient.getEventTypeNames and BrokerEvent.getBaseTypeName

getUCCharField


getUCCharSeqField



BrokerFieldNotFoundException The tag envelope field is not set for this event.


BrokerInvalidTypeDefException The event is not associated with a Broker client.



getUCStringField


getUCStringSeqField


hasBeenModified

boolean hasBeenModified()

Returns true if this event has been modified.

See also: BrokerEvent.clearModificationFlag and BrokerEvent.setModificationFlag

isAckReply

boolean isAckReply()

Returns true if this event is of type Adapter::ack, meaning it is an acknowledgment reply. Returns false if the event is not an acknowledgment.

See also: BrokerEvent.isErrorReply, BrokerEvent.isLastReply, and BrokerEvent.isNullReply

isErrorReply

boolean isErrorReply()

Returns true if this event is of type Adapter::error, otherwise false is returned.

See also: BrokerEvent.isAckReply, BrokerEvent.isLastReply, and BrokerEvent.isNullReply

isFieldSet

boolean isFieldSet( String field_name) throws BrokerException

Returns true if the value of the specified field in this event has been set, otherwise false is returned.

field_name The name of the sequence field to be checked.






isLastReply

boolean isLastReply()

Returns true if this event is the last in a reply sequence, indicated by the envelope fields appSeqn and appLastSeqn being equal. Otherwise false is returned.

See also: BrokerEvent.isAckReply, BrokerEvent.isErrorReply, and BrokerEvent.isNullReply

isNullReply

boolean isNullReply()

Returns true if this event is a null reply, indicated by the envelope fields appSeqn and appLastSeqn both being equal to -1. Otherwise false is returned.

See also: BrokerEvent.isAckReply, BrokerEvent.isErrorReply, and BrokerEvent.isLastReply

set<type>Field

The set<type>Field methods have a general syntax:

void set<type>Field( String field_name, <type> value) throws BrokerException



field_name The name of the event field being set.




The set<type>Field methods set a the destination event field field_name to the source value. Event field values can be set in any order. To set an entire sequence field in a single method call, use the set<type>SeqField method.

Note: Attempting to set an event field with a type that does not match the event's definition will result in an exception being thrown. For information on defining events, see the Software AG Designer Online Help. No error will be returned if setStringField is used to set a field whose type is FIELD_TYPE_UNICODE_STRING. In these cases, the ANSI string that is supplied to setStringField will automatically be converted to a unicode string.

Note: If you use the setCharField or setStringField method to store a Unicode character or string into an ANSI field, all Unicode characters that cannot be mapped to an ANSI character will be replaced with an underscore character ("_").

value The source value for the event field. The field value is different depending on the method as follows:

setBooleanField has a field value type of boolean.

setByteField has a field value type of byte.

setCharField has a field value type of char.

setDateField has a field value type of BrokerDate.

setDoubleField has a field value type of double.

setFloatField has a field value type of float.

setIntegerField has a field value type of int.

setLongField has a field value type of long.

setShortField has a field value type of short.

setStringField has a field value type of String.

setUCCharField has a field value type of char.

setUCStringField has a field value type of String.


BrokerFieldNotFoundException The event is associated with a client, but the specified field_name does not exist in the event.

BrokerFieldTypeMismatchException The field is not of the specified type or the field_name incorrectly accesses a type, such as using a subscript on a non-sequence field.




See also: BrokerEvent.set<type>SeqField, BrokerEvent.setField, BrokerEvent.setStringFieldToSubstring, and BrokerEvent.setStructFieldFromEvent

set<type>SeqField

void set<type>SeqField( String field_name, int src_offset, int dest_offset, int n, <type> value) throws BrokerException



src_offset Elements to skip from the beginning of the source elements.

dest_offset Elements to skip from the beginning of the sequence. If set to ENTIRE_SEQUENCE, the sequence field size will be resized to match the size of the source array.

n Number of source elements. If set to AUTO_SIZE, all elements of the source array will be used.

value The array of source value for the event field. The sequence value type is different depending on the method as follows:

setBooleanSeqField has a sequence value type of boolean[].

setByteSeqField has a sequence value type of byte[].

setCharSeqField has a sequence value type of char[].

setDateSeqField has a sequence value type of BrokerDate[].

setDoubleSeqField has a sequence value type of double[].

setFloatSeqField has a sequence value type of float[].

setIntegerSeqField has a sequence value type of int[].

setLongSeqField has a sequence value type of long[].

setShortSeqField has a sequence value type of short[].

setStringSeqField has a sequence value type of String[].

setUCCharSeqField has a sequence value type of char[].

setUCStringSeqField has a sequence value type of String[].




The set<type>SeqField methods sets the destination sequence field, field_name in this event to the sequence of values contained in value. To set a non-sequence field, use one of the set<type>Field methods.

Each of the set<type>SeqField methods can overwrite all or part of the destination sequence field. These methods can also cause the destination sequence to grow, if a larger number of elements are stored into the sequence. These methods never reduce the number of elements in the destination sequence. You must use setSequenceFieldSize method to reduce the size of a sequence.

Note: Attempting to set an event field with a type that does not match the event's definition will result in an exception being thrown. For information on defining event types, see the Software AG Designer Online Help. No error will be returned if setStringSeqField is used to set a field whose type is FIELD_TYPE_UNICODE_STRING. In these cases, the ANSI string that is supplied to setStringSeqField will automatically be converted to a unicode string.

See also: BrokerEvent.set<type>Field, BrokerEvent.setField, BrokerEvent.setSequenceField, and BrokerEvent.setStructSeqFieldFromEvents

setBooleanField

See BrokerEvent.set<type>Field.

setBooleanSeqField

See BrokerEvent.set<type>SeqField.

setByteField







BrokerOutOfRangeException The src_offset is not within the size of value, dest_offset is less than zero, or n is less than zero.



setByteSeqField


setCharField


setCharSeqField


setDateField


setDateSeqField


setDoubleField


setDoubleSeqField


setField

void setField( String field_name, short field_type, Object value) throws BrokerException

Sets a regular field in this event with the specified field_name. The field_type must be set to one of the following variables, declared in BrokerTypeDef.

FIELD_TYPE_BYTE FIELD_TYPE_SHORT FIELD_TYPE_INT FIELD_TYPE_LONG FIELD_TYPE_FLOAT FIELD_TYPE_DOUBLE FIELD_TYPE_BOOLEAN FIELD_TYPE_DATE


field_type The type of the field value being set.

value The value for the event field.



FIELD_TYPE_CHAR FIELD_TYPE_STRING FIELD_TYPE_UNICODE_CHAR FIELD_TYPE_UNICODE_STRING FIELD_TYPE_SEQUENCE FIELD_TYPE_STRUCT FIELD_TYPE_UNKNOWN

Note: Attempting to set an event field with a type that does not match the event's definition will result in an exception being thrown. For information on defining events, see the Software AG Designer Online Help. No exception will be thrown if a FIELD_TYPE_STRING value is used to set a field whose type is FIELD_TYPE_UNICODE_STRING. In these cases, the ANSI string that is supplied will automatically be converted to a unicode string.

Note: Do not attempt to use the setField method to set sequence fields. Use one of the set<type>SeqField methods or the setSequenceField method to set sequence fields.

See also: BrokerEvent.set<type>Field, BrokerEvent.set<type>SeqField, BrokerEvent.setSequenceField, and BrokerEvent.setStringFieldToSubstring

setField

void setField( String field_name, BrokerField value) throws BrokerException

Sets a regular field in this event with the specified field_name. The field_type of the value must be set to one of the following variables, declared in BrokerTypeDef.





BrokerInvalidTypeException The field_type is FIELD_TYPE_SEQUENCE or is not a supported type.

BrokerNullParameterException The field_name or value parameter is null.





FIELD_TYPE_BYTE FIELD_TYPE_SHORT FIELD_TYPE_INT FIELD_TYPE_LONG FIELD_TYPE_FLOAT FIELD_TYPE_DOUBLE FIELD_TYPE_BOOLEAN FIELD_TYPE_DATE FIELD_TYPE_CHAR FIELD_TYPE_STRING FIELD_TYPE_UNICODE_CHAR FIELD_TYPE_UNICODE_STRING FIELD_TYPE_SEQUENCE FIELD_TYPE_STRUCT

Note: Attempting to set a an event field with a type that does not match the event's definition will result in an exception being thrown. For information on defining events, see the Software AG Designer Online Help. No exception will be thrown if a FIELD_TYPE_STRING value is used to set a field whose type is FIELD_TYPE_UNICODE_STRING. In these cases, the ANSI string that is supplied will automatically be converted to a unicode string.

Note: Do not attempt to use the setField method to set sequence fields. Use one of the set<type>SeqField methods or the setSequenceField method to set sequence fields.

See also: BrokerEvent.set<type>Field, BrokerEvent.set<type>SeqField, BrokerEvent.setSequenceField, and BrokerEvent.setStringFieldToSubstring

setFloatField






BrokerInvalidTypeException The field_type of the value is FIELD_TYPE_SEQUENCE or is not a supported type.

BrokerNullParameterException The field_name or field parameter is null.



setFloatSeqField


setIntegerField


setIntegerSeqField


setLongField


setLongSeqField


setModificationFlag

void setModificationFlag()

Sets the modification flag for this event. Subsequent calls to BrokerEvent.hasBeenModified will return true.

setPriority

void setPriority(int priority) throws Broker Exception

Sets the message priority before publishing the message. Use it to specify the message priority using values from 0-9, where 0 is the lowest priority and 9 is the highest priority (expedited processing). The default is 4. For more information about how to use priority ordering, see “Priority Ordering for Broker Queues” on page 57.

See also: BrokerEvent.getPriority

setPublishSequenceNumber


void setPublishSequenceNumber( long seqn)

seqn The sequence number to set for this event. Set to a value greater than zero if you want the Broker to check for the publication of duplicate events.



Sets the publish sequence number for this event to seqn prior to publishing an event. Not setting an event's publish sequence number, or setting it to 0 or a -ve value, indicates to the Broker that you do not want the publish sequence numbering rules to be applied to the event.

The Broker will discard any event with a non-zero sequence number if it has already processed an event with an equal or larger sequence number. Events with an event sequence number of zero are not subject to these rules. Sequence numbers have a 64-bit representation and, therefore, are never expected to wrap back to 1 or to repeat.

Note: The BrokerEvent.setPublishSequenceNumber method does not actually set the pubSeqn envelope field. Instead, it specifies the sequence number that the Broker is to set on the next event published by your Broker client.

See also: BrokerEvent.getPublishSequenceNumber and BrokerClient.publish

setSequenceField

void setSequenceField( String field_name, short field_type, int src_offset, int dest_offset, int n, Object value) throws BrokerException

Sets the values of the destination sequence field field_name to the values contained in the source sequence. The elements in the source and destination sequence are of the type represented by field_type, which must be set to one of the following variables, declared in BrokerTypeDef.


field_type The type of the field value being set.





Field Name Field Value Type

FIELD_TYPE_BYTE byte[]



This method can overwrite all or part of the destination sequence field or cause the destination sequence to grow, if a larger number of elements are stored into the sequence. This method never reduces the number of elements in the destination sequence: You must use setSequenceFieldSize method to reduce the size of a sequence.

If you set five elements (a, b, c, d, e) into a sequence at location 0, the sequence would appear as: [a b c d e]. If you then set three elements (1, 2, 3) into this same sequence at location 0, the sequence would then appear as: [1 2 3 d e].

Note: Attempting to set an event field with a type that does not match the event's definition will result in an exception being thrown. For information on defining event types, see the Software AG Designer Online Help. No error will be returned if FIELD_TYPE_STRING values are used to set a sequence field whose type is FIELD_TYPE_UNICODE_STRING. In these cases, the ANSI strings that are supplied will automatically be converted to unicode strings.

FIELD_TYPE_SHORT short[]

FIELD_TYPE_INT int[]

FIELD_TYPE_LONG long[]

FIELD_TYPE_FLOAT float[]

FIELD_TYPE_DOUBLE double[]

FIELD_TYPE_BOOLEAN boolean[]

FIELD_TYPE_DATE BrokerDate[]

FIELD_TYPE_CHAR char[]

FIELD_TYPE_STRING String[]

FIELD_TYPE_UNICODE_CHAR char[]

FIELD_TYPE_UNICODE_STRING String[]

FIELD_TYPE_STRUCT Use the method setStructFieldFromEvent





Field Name Field Value Type



See also: BrokerEvent.getSequenceField, BrokerEvent.set<type>SeqField, and BrokerEvent.setStructSeqFieldFromEvents

setSequenceFieldSize

void setSequenceFieldSize( String field_name, int size) throws BrokerException

Sets the number of elements in the sequence field field_name in this event.

See also: BrokerEvent.getSequenceFieldSize, BrokerEvent.set<type>SeqField, BrokerEvent.setSequenceField, and BrokerEvent.setStructSeqFieldFromEvents

setShortField


BrokerInvalidTypeException The field_type is FIELD_TYPE_SEQUENCE or is not a supported field type.


BrokerOutOfRangeException The src_offset is not within the size of value, dest_offset is less than zero, or n is less than -1.


size The new size for the sequence.






BrokerOutOfRangeException The size is less than zero.




setShortSeqField


setStringField


setStringFieldToSubstring

void setStringFieldToSubstring( String field_name, int offset, int nc, String value) throws BrokerException

Sets the value of the string field field_name to a substring from value.

See also: BrokerEvent.set<type>Field and BrokerEvent.setStringField

setStringSeqField



offset Elements to skip from the beginning of the source elements.

nc Number of source characters. If set to -1, the entire contents of value will be used.







BrokerOutOfRangeException The offset is not within the size of the string or if nc would exceed the size of the string.



setStructFieldFromEvent

void setStructFieldFromEvent( String field_name, BrokerEvent value) throws BrokerException

Sets the value of the structure field field_name from value, which is another BrokerEvent containing the structure field values. Any envelope fields contained in value will be ignored.

See also: BrokerEvent.setField, BrokerEvent.set<type>Field, and BrokerEvent.setStructSeqFieldFromEvents

setStructSeqFieldFromEvents

void setStructSeqFieldFromEvents( String field_name, int src_offset, int dest_offset, int n, BrokerEvent value[]) throws BrokerException

field_name The name of the event field being set. You can set this to null if you want to set the top level of the event.






BrokerNullParameterException The value parameter is null.






Sets the destination structure sequence field field_name from the specified source value, which is expressed as an array of events. Each of the events in value should contain fields that correspond to the fields of a structure. Envelope fields on the value events are ignored.

See also: BrokerEvent.setSequenceField, BrokerEvent.set<type>SeqField, and BrokerEvent.setStructSeqFieldFromEvents

setTag

void setTag( int tag) throws BrokerException

Sets this event's tag envelope field to tag. This is equivalent to:

setIntegerField("_env.tag", tag);

See also: BrokerEvent.getTag and BrokerClient.makeTag

setUCCharField



value The array of values for the event field sequence.





BrokerNullParameterException The field_name or value parameter is null, or at least one of the elements in value is null.

BrokerOutOfRangeException The src_offset is not within the size of value, dest_offset is less than zero, or n is less than -1.

tag The tag to set for this event.



setUCCharSeqField


setUCStringField


setUCStringFieldToSubstring

void setUCStringFieldToSubstring( String field_name, int offset, int nc, String value) throws BrokerException

Sets the value of the Unicode string field field_name to the specified sub-string value. The number of characters to be set is specified by nc. The offset into the field is specified by char_offset.

See “Specifying Field Names” on page 86 for complete information on specifying field_name.

See also: BrokerEvent.set<type>Field and BrokerEvent.setStringField


offset Elements to skip from the beginning of the source elements.

nc Number of source characters. If set to -1, the entire contents of value will be used.







BrokerOutOfRangeException The offset is not within the size of the string or if nc would exceed the size of the string.



setUCStringSeqField


stringFromANSI

static String stringFromANSI( String st)

Returns an Unicode String object that is a conversion of the specified ANSI String object st. The returned String contains only Unicode characters. Any uses of '\\u' escape sequences in st are converted to proper Unicode characters in the returned String.

See also: stringToANSI

stringToANSI

static String stringToANSI( String st)

Returns an ANSI String object that is a conversion of the specified Unicode String object st. The returned String contains only ANSI characters. Any Unicode characters in st that do not map to ANSI characters are replaced with '\u' escape sequences in the returned String.

See also: stringFromANSI

toBinData

byte[] toBinData();

Returns a binary array representation of this BrokerEvent. The binary data can be stored on disk for later retrieval and conversion back to a BrokerEvent, using the BrokerEvent.fromBinData method.

See also: BrokerEvent.fromBinData

toFormattedString

String toFormattedString( String formatString) throws BrokerException

Returns a string containing the values of fields from this event. The formatString specifies which event fields are to be extracted and their format.

For information on setting formatString, see BrokerFormat.

st The ANSI string to be converted.

st The Unicode string to be converted.

formatString Specifies the format of the output string.




toFormattedString(format, java.util.Locale.US);

See also: BrokerFormat

toFormattedString

String toFormattedString( String formatString, java.util.Locale locale) throws BrokerException

Uses the specified locale to return a string containing the values of fields from this event. The formatString specifies which event fields are to be extracted and their format.


See also: BrokerFormat.

toLocalizedFormattedString

String toFormattedString( String formatString) throws BrokerException

Returns a string containing the values of fields from this event. The formatString specifies which event fields are to be extracted and their format.



toFormattedString(format, Locale.getDefault());

See also: BrokerFormat

toLocalizedString

String toLocalizedString()

Returns a string containing the values of fields from this event, using the current Locale.


toString(Locale.getDefault());

See also: BrokerEvent.toString


locale The locale to be used for formatting the string.




toObject


void toObject( Object obj) throws BrokerException

Copies the values of all the fields in this event that have members in obj which have the same name.

The obj object can define boolean data members with names in the format $<event_field_name\>, where <event_field_name\> corresponds to a field in this event. These $-style data members will be set to 0 (false) if their corresponding event field has not been set.

If this BrokerEvent was created using a BrokerClient, the event will be type-checked and data members in obj that correspond to un-set fields will be set to their default values and any corresponding $-style data member will be set accordingly.

See also: BrokerEvent.fromObject.

toString

String toString()

Returns a string with this event's content, suitable for display or printing. Invoking this method is equivalent to invoking:

toString(java.util.Locale.US);

See also: BrokerEvent.toFormattedString and BrokerEvent.toLocalizedString

toString

String toString( java.util.Locale locale)

obj The object whose data members will be set, using the field values in this event.


BrokerFieldNotFoundException A public data member in obj does not have a corresponding field with the same name in this BrokerEvent.

BrokerFieldTypeMismatchException The data type of a public data member in obj does not match the data type of its corresponding field in this BrokerEvent.




Uses the specified locale to format a string with this event's content that is suitable for display or printing.


toString

String toString( int indent_level)

Returns a string with this event's content, suitable for display or printing.


toString

String toString( int indent_level, java.util.Locale locale)

Uses the specified locale to format a string with this event's content that is suitable for display or printing.


validate

void validate( BrokerClient client) throws BrokerException

Validates this event within the context of the specified Broker client. If client is null, the client used in the creation of this event, if any, is used.

An event passes validation if its event type exists on the Broker and if the field names and types match the Broker's definition for the event.


indent_level The number of 4-character spaces to use for indentation.



client The Broker client context to use for validation.



BrokerException

class BrokerException extends java.lang.exception

This abstract base class is used to derive all webMethods Broker exceptions that might be thrown to report API, communications, and Broker failures. For a complete listing of the exceptions derived from this class, see “API Exceptions” on page 413.

Methods

getCode

int getCode()

Returns the exception code for this object. See “Determining the Exception Type” on page 138 for more information on handling exceptions.

See also: BrokerException.getMinorCode

getDiagnostics

static int getDiagnostics()

This static method returns the current system diagnostics level. The possible return values and their meanings are:

See also: BrokerException.setDiagnostics

getMessage

String getMessage()

Returns a string containing the exception message.


BrokerFieldTypeMismatchException The event did not pass validation.

BrokerInvalidClientException The client parameter is null and the event is not type checked.


0 No error output will be produced.


2 Produces all error output for all methods.



getMinorCode

int getMinorCode()

Returns the minor code for this exception. See “Determining the Exception Type” on page 138 for more information on handling exceptions.

See also: BrokerException.getCode

setDiagnostics

static int setDiagnostics( int diag) throws BrokerException

Sets the system diagnostic level to the value specified by diag. The diagnostic level determines the type of webMethods Broker error reporting that will occur for your application. The possible values and their meanings are:

See also: BrokerException.getDiagnostics

toCompleteString

String toCompleteString()

Returns a string that describes this BrokerException in greater detail than the method BrokerException.toString.

See also: BrokerException.toString

toString

String toString()

Returns a string with contents of this BrokerException, suitable for display or printing.

See also: BrokerException.toCompleteString

diag The new diagnostic level to set.


0 No error output will be produced. Use this setting for deployed applications.


2 Produces all error output for all methods. Use this setting when debugging an application.



BrokerField

class BrokerField extends java.lang.Object

This class represents a field within a BrokerEvent.

Variables

type

short type

The field's type, represented by one of the FIELD_TYPE_* values in BrokerTypeDef on page 407.

value

Object value

The value for the field. The object's class depends on the field's type.

Constructors

BrokerField

BrokerField()

Creates an empty field object with no value and no type.

BrokerField

BrokerField( short field_type, Object field_value)

Creates a BrokerField with the specified field_type and field_value.

BrokerFilter

class BrokerFilter extends java.lang.Object

field_type The field's type. Must be one of the of the values defined by BrokerTypeDef.

field_value The field's value.



This class represents an event filter for determining if a BrokerEvent matches user-defined criteria.

BrokerFilter objects are used locally, by a client application, to quickly determine whether an event matches a specified set of characteristics.

Constructors

BrokerFilter

BrokerFilter( BrokerClient client, String event_type_name, String filter_string) throws BrokerException

Creates a BrokerFilter object for the specified client and event_type_name, using the filter criteria specified in filter_string.

BrokerFilter

BrokerFilter( BrokerClient client, String event_type_name, String filter_string, java.util.Locale locale) throws BrokerException

client The Broker client for which this filter is being created.

event_type_name The name of the event to be filtered. A wildcard can be added to the end of the event type name. See “Using Wildcards” on page 92 for more information. See “Parameter Naming Rules” on page 419 for restrictions on event type names.

filter_string The filter string.


BrokerFilterParseException A error was encountered while parsing the filter_string.

BrokerNullParameterException The client or event_type parameter is null.

client The Broker client for which this filter is being created.



Creates a BrokerFilter object for the specified client and event_type_name, using the filter criteria specified in filter_string.

The locale overrides the current locale defined for your application. The locale allows an application to adapt itself to different languages, character sets, time zones, date formats.

Methods

getEventTypeName

String getEventTypeName()

Returns the event type name for which this filter was created.

getFilterString

String getFilterString()

Returns the filter string defined for this filter.

match

boolean match( BrokerEvent event) throws BrokerException

Tests the event against this filter and returns true if the event matches the filter's criteria. If the event is not of the specified event type or does not match the filter's criteria, false is returned.

event_type_name The fully-qualified name of the event to be filtered. A wildcard can be added to the end of the event type name. See “Using Wildcards” on page 92 for more information. See “Parameter Naming Rules” on page 419 for restrictions on event type names.

filter_string The filter string.

locale The locale to be used for your filter.


BrokerFilterParseException A error was encountered while parsing the filter_string.

BrokerNullParameterException The client or event_type parameter is null.

event The event to be tested with this filter.



toString

String toString()

Returns a string with information on this BrokerFilter, suitable for display or printing.

BrokerFormat

class BrokerFormat extends java.lang.Object

This class encapsulates formatting specifications for an event's fields. It provides methods for generating a formatted string, given a format specification and an event. The format specification allows you to define which event fields you want to put into the output string and the format of the output in a formatString.

You can generate the formatString by first invoking preparse with a format specification. Next, invoke assemble with the output of preparse and an event reference to generate the final output string. This allows you to call preparse once and then use the same format specification over and over again with different events.

You can also generate the formatString in one invocation by calling the format method.

Specifying Field Names and Formats

1 Field names must be preceded with a $ character.

2 Field names can optionally be enclosed in curly braces.

3 Format options must be placed at the end of the field name and be separated with a : character.

4 If a minimum field width is specified, it must follow the : delimiter and precede the format specifier.

5 Use a backslash to escape any reserved characters, such as the $ character.

You could use either of the following formats to refer to a string field named age:

$age:c

or

${age:c}


BrokerFilterRuntimeException A error was encountered while parsing this filter.




Format options

The following formatting options are supported:

Constructor

BrokerFormat

BrokerFormat( String format_string)

Parses the format_string into tokens and creates a BrokerFormat object.

Format option Description

s Encloses the output value in single quotes. Single quotes occurring in the value are escaped with a backslash character.

d Encloses the output value in double quotes. Double quotes occurring in the value are escaped with a "\" character.

q Provides SQL-style quoting. This is like the :s option, but the escape character is a single quote instead of slash.

v Replaces each field reference with a bind variable place holder. The default style is :v1, :v2. You can change this option to use ? by calling the setFormatMode method.

c Outputs a numeric value from a field containing a string. Any non-numeric portions of the string field will be discarded. "123x" will become "123".

<number> Modifies the above options by specifying a minimum field length together with one of the options above. The value of string field containing AB with a format option of 5d will result in the output "AB". The field is always left justified and right padded as necessary to meet the field length.

format_string The format string that is to be parse into tokens.



Methods

assemble

static String assemble( BrokerEvent event, Vector tokens) throws BrokerException

Returns a string created by replacing each token in the list of tokens with a field value from event.


assemble(events, tokens, java.util.Locale.US);

See also: BrokerFormat.format, BrokerFormat.formatBindVariable, BrokerFormat.preparse, and BrokerFormat.setFormatMode

assemble

static String assemble( BrokerEvent event, Vector tokens, java.util.Locale locale) throws BrokerException

Uses the specified locale to return a string which is created by replacing each token in the list of tokens with a field value from event.

event The event to be formatted

tokens The list of formatting tokens.


BrokerFieldNotFoundException A field referenced in tokens was not found in the event

BrokerInvalidTypeException A field referenced in tokens is of an unsupported type.

event The event to be formatted




BrokerFieldNotFoundException A field referenced in tokens was not found in the event




assemble

static String assemble(Vector tokens)

Returns a string assembled from the list of tokens, without an event field reference.


format

String format()

Returns a formatted string without any event data.

See also: BrokerFormat.assemble, BrokerFormat.formatBindVariable, BrokerFormat.preparse, and BrokerFormat.setFormatMode

format

String format( BrokerEvent event) throws BrokerException

Returns a string containing the field values from event.


format(event, java.util.Locale.US);


format

String format( BrokerEvent event, java.util.Locale locale) throws BrokerException

BrokerInvalidTypeException A field referenced in tokens is of an unsupported type.


event The event to be formatted.





Uses the specified locale to return a string containing the field values from event.


format

static String format( BrokerEvent event, String *format_string) throws BrokerException

Returns a string containing the field values from event, as specified in the format_string. Lines in the resulting string are separated with newline characters '\n'.


format(event, format, java.util.Locale.US);


format

static String format( BrokerEvent event, String *format_string, java.util.Locale locale) throws BrokerException

Uses the specified locale to return a string containing the field values from event, as specified in the format_string. Lines in the resulting string are separated with newline characters '\n'.




format_string The format string to use to format the event.


format_string The format string to use to format the event.




formatBindVariable

static String formatBindVariable( int index, StringBuffer place_holder_name) throws BrokerException

This method gives you access to the variable names that are set up with the format option. You must invoke preparse to parse the format specifier.

Given a format specifier of:

INSERT INTO table (column1, column2) VALUES (${field1:v}, ${field2:v})

then this string gets formatted to either:

INSERT INTO table (column1, column2) VALUES (:v0, :v1)

or

INSERT INTO table (column1, column2) VALUES (?, ?)

depending on the mode set for the :v option by calling setFormatMode().

Calling formatBindVariable( 0, placeHolderName) will return "field1", and set placeHolderName to either ":v0" or "?".

See also: BrokerFormat.assemble, BrokerFormat.format, BrokerFormat.preparse, and BrokerFormat.setFormatMode

getTokenCount

int getTokenCount()

Returns the number of tokens.

getTokenValue

String getTokenValue( int t)

Returns the value of the token with the specified index. The value is either a fixed string, or the name of an event field

See also: BrokerFormat.isReferenceToken

index The index to use.

place_holder_name The place holder to use.

t The index associated with the token whose value is to be returned.



isReferenceToken

boolean isReferenceToken( int t)

Returns true if the token with the specified index is a reference to an event field.

See also: BrokerFormat.getTokenValue

preparse

static Vector preparse( String formatString)

Breaks format_string into a list of tokens.

See also: BrokerFormat.assemble, BrokerFormat.format, BrokerFormat.formatBindVariable, and BrokerFormat.setFormatMode

setFormatMode

static boolean setFormatMode( String format_option String mode)

Sets the mode for the format_option. Returns true if the mode was altered, otherwise false is returned.

Consider the following format string:

column1 = ${field1:v}, column2 = ${field2:v}

If you can call this method as:

setFormatMode("v", "?")

invoking BrokerFormat.assemble will produce this output:

column1 = ?, column2 = ?

If you call this method as setFormatMode("v", ":") invoking BrokerFormat.assemble will produce this output:

column1 = :v0, column2 = :v1

t The index associated with the token being tested.

formatString The format string to use.

format_option The format option to be modified. Currently, v is the only format option whose mode can be altered.

mode The new mode. You can specify only “?” or “:”.



See also: BrokerFormat.assemble, BrokerFormat.format, BrokerFormat.formatBindVariable, and BrokerFormat.preparse

BrokerMonitorClientclass BrokerMonitorClient extends java.lang.Object

Creates a Broker Monitor client. A monitor client is used by administration applications to manage Broker Server. When creating a BrokerMonitorClient, you do not have to pass a port number. The broker_host parameter should contain the name of the system on which your Broker Server is running. If you pass a port number, it will be ignored.

Make sure the Broker Monitor process is running before creating BrokerMonitorClient object.

BrokerMonitorClient should not take in a port number. When creating a BrokerMonitorClient object only the host name should be passed.

This class is used to manage Broker Server. Broker Monitor should be up and running before working with BrokerMonitorClient class.

Constructors

BrokerMonitorClient

BrokerMonitorClient( java.lang.String broker_host) throws BrokerException

Creates a Broker Monitor client. A monitor client is used to by administration applications to manage Broker Servers:

Possible Exceptions Description

BrokerCommFailureException A problem occurred when establishing the connection.

BrokerHostNotFoundException The specified host does not exist.

BrokerNotRunningException The host exists but a Broker Monitor does not exist on that host.

BrokerNullParameterException broker_host is null.



Methods

destroy

void destroy() throws BrokerException

Destroys the monitor client. Disconnects from the Broker Monitor. This might throw any communications exception, but the local client object is marked as disconnected even if an exception is thrown.

getHostName

java.lang.String getHostName()

Get the host name of the Broker Monitor.

getPort

int getPort()

Get the port being used by the Broker Monitor.

getServerLogEntries

BrokerServerLogEntry[] getServerLogEntries( int base_port, BrokerDate first_entry, java.lang.String locale, int num_entries)

Get a set of server log entries, for the server listening on the given base port number. You supply the date for the first entry you are interested in, and can provide a maximum number of entries to receive. If num_entries is '-1' then it gets all entries. Note that getting all entries can be a performance and/or memory problem. If first_entry is null, returns entries starting from the beginning of the log. locale can be used to request a specific locale. If NULL, then the server's default locale is used. The server's default locale is also used if you request a locale that the server does not support.


BrokerInvalidClientException The client has been destroyed.



BrokerIncompatibleVersionException The version of the broker is not known to this operation.

BrokerOutOfRangeException num_entries is less than -1.

BrokerNoPermissionException The client has limited access.



getServerLogStatus

BrokerServerLogInfo getServerLogStatus( int base_port) throws BrokerException

Get the server log status, for the server listening on the given base port number.

getServerRunStatus

int getServerRunStatus( int port) throws BrokerException

Get the current status of a Broker Server. Returns one of the BrokerServerClient.SERVER_STATUS_* values.

getServers

BrokerServerInfo[] getServers() throws BrokerException

Get config information about all Broker Servers on the host.

getVersion

java.lang.String getVersion() throws BrokerException

Get the version of the Broker Monitor.

getVersionNumber

int getVersionNumber()




BrokerNoPermissionException The client has limited acces.s



BrokerUnknownServerException A Server is not configured on the specified port.





Get the Broker Monitor's version number. Returns one of the BrokerClient.VERSION_* content values.

If the Broker Monitor is newer than the client's version, the client's version is reported.

pruneMonitorLog

void pruneMonitorLog( int base_port, BrokerDate older_than)

Delete entries from the monitor's log. Deletes all entries from the given date (inclusive) and older.

reloadConfig

void reloadConfig() throws BrokerException

Cause the monitor to re-read its configuration for all servers.

reloadConfigForServer

void reloadConfigForServer(int port) throws BrokerException

Cause the monitor to re-read its configuration for a single server.

startServer

void startServer( int port) throws BrokerException

Start a server.




BrokerNullParameterException If older_than is null.

BrokerNoPermissionException The client has limited access






toString

java.lang.String toString()

Get a string with the monitor client information in a form suitable for human viewing. Returns null if the monitor client is not valid. Overrides: toString in class java.lang.Object

BrokerSSLCertificate

class BrokerSSLCertificate extends java.lang.Object

This class is used to describe an SSL certificate. For information on using SSL and certificates, see “Working with SSL” on page 197

Variables

begin_date

BrokerDate begin_date

The date when this certificate became valid.

distinguished_name

String distinguished_name

The distinguished name of the entity for which this certificate was issued.

end_date

BrokerDate end_date

The date this certificate expires.

issuer_distinguished_name

String issuer_distinguished_name

The distinguished name of the entity that issued this certificate






status

String status

A string that describes the status of the certificate using one of the following strings:

VALID

PENDING

EXPIRED

CRL EXPIRED

REVOCATION UNKNOWN

REVOKED

Constructors


BrokerSSLCertificate()

Creates an empty certificate description.


BrokerSSLCertificate( String new_distinguished_name, String new_issuer_distinguished_name, String new_status, BrokerDate new_begin_date, BrokerDate new_end_date)

Creates a certificate description with the specified event distinguished name, issuer distinguished, status, begin date, and end date. See status on page 382 for the values for new_status.

BrokerSubscription

class BrokerSubscription extends java.lang.Object

new_distinguished_name The distinguished name for the certificate.

new_issuer_distinguished_name The distinguished name for the entity that issued the certificate.

new_status The status of the certificate.

new_begin_date The date this certificate became valid.

new_end_date The date this certificate expires.



This class represents an event subscription and is used by BrokerClient objects to register subscriptions with the Broker.

For information on using subscriptions, see “Subscribing to and Receiving Events” on page 89.

Variables

event_type_name

String event_type_name

The event type name for this subscription. See “Parameter Naming Rules” on page 419 for restrictions on event type names.

filter

String filter

The event filter string.

sub_id

int sub_id

The subscription identifier.

Constructors

BrokerSubscription

BrokerSubscription()

Creates an empty subscription.

BrokerSubscription

BrokerSubscription( String type_name, string filter_string)

Creates subscription with the specified event type_name and filter_string. The sub_id member is set to zero.

type_name The event type name for this subscription. See “Parameter Naming Rules” on page 419 for restrictions on event type names.

filter_string The filter for this subscription.



An asterisk can be added to the end of the type_name as a wildcard if you want to specify multiple event types. See “Using Wildcards” on page 92 for more information.

BrokerSubscription

BrokerSubscription( int id, String type_name, string filter_string)

Creates subscription with the specified subscription id, event type_name and filter_string.

An asterisk can be added to the end of the type_name as a wildcard if you want to specify multiple event types. See “Using Wildcards” on page 92 for more information.

Subscription IDs do not uniquely identify a particular subscription, so you can create different subscriptions and with the same subscription ID. See “Uniqueness of Subscriptions” on page 91 for more information for more information on what differentiates subscriptions from one another.

Methods

toString

String toString( int indent_level, boolean include_sub_id)

Converts the subscription into a string format suitable for display or printing.

BrokerTransactionalClient

class BrokerTransactionalClient

id A subscription identifier.

type_name The event type name for this subscription. See “Parameter Naming Rules” on page 419 for restrictions on event type names.

filter_string The filter for this subscription.


include_sub_id If set to true, the subscription identifier will be included in the string.



Constructors

BrokerTransactionalClient

BrokerTransactionalClient( java.lang.String broker_host, java.lang.String broker_name, java.lang.String client_id, java.lang.String client_group, java.lang.String app_name, BrokerConnectionDescriptor desc) throws BrokerException

Creates a Broker client that is transactional. broker_name can be null to request the default Broker. client_id can be null to request the Broker to create an identifier (usually used with destroy-on-disconnect clients). desc can be null to create a default connection.


BrokerClientExistsException If a client using the specified client ID already exists.



BrokerInvalidClientIdException If the ID contains illegal characters.

BrokerInvalidNameException If app_name contains illegal characters.

BrokerNoPermissionException If permission to join the specified client group is denied.

BrokerNotRunningException If the host exists but no Broker is running on that host.

BrokerNullParameterException If broker_host, client_group, or app_name are null.

BrokerSecurityException If a secure connection is attempted but is rejected by the Broker.

BrokerUnknownBrokerNameException If the specified broker does not exist. If broker_name is null, this indicates that there is no default Broker.

BrokerUnknownClientGroupException If the specified client group does not exist on the Broker.



Methods

abort

void abort() throws BrokerException

Aborts the open transaction, discarding all work previously performed, and invalidates Rollback the transaction the context.

See also: commit()

abortAll

static void abortAll(BrokerTransactionalClient[] tx_clients) throws BrokerException

Aborts the given list of open transactions, discarding all work previously performed, and invalidates the context. Rollback the transaction.


BrokerTxClosedException This exception is thrown by Information Broker client methods when an action is attempted on a BrokerClient transaction which has been either committed or aborted.

BrokerInvalidClientException This exception is thrown by Information Broker client methods when a BrokerClient is determined to be invalid because it has already been disconnected or destroyed.

BrokerInvalidTxException This exception is thrown by Information Broker client methods when a name is specified which does not exist in the resource being accessed.





See also: commit()

acknowledge

public void acknowledge(long seqn) throws BrokerException

Acknowledge the single event specified. A value of zero acknowledges all outstanding events. In addition to the listed exceptions, any communications exception can be thrown.

acknowledge

public void acknowledge(long[] seqn) throws BrokerException

Acknowledge the array of events with the given seqn numbers. A value of zero acknowledges all outstanding events. In addition to the listed exceptions, any communications exception can be thrown.



Description copied from class: BrokerClient

Overrides: acknowledge in class BrokerClient

Tags copied from class: BrokerClient



seqn is not a valid event to acknowledge.


BrokerOutOfRangeException seqn is less than zero.


Overrides: acknowledge in class BrokerClient




acknowledgeThrough

public void acknowledgeThrough(long seqn) throws BrokerException

Acknowledges all events through the event specified. A value of zero acknowledges all outstanding events. In addition to the listed exceptions, any communications exception can be thrown.

beginTransaction

long beginTransaction( java.lang.String external_id) throws BrokerException

Starts a transaction. The operations done after this call will be performed after the commit method is called. If aborted, all the operations after this call will be ignored.








Overrides: acknowledgeThrough in class BrokerClient







external_id A user defined, externally generated transaction identifier. Can be null.



commit

void commit() throws BrokerException

Commits the open transaction. All work performed on this context will be finalized.

See also: abort()

commitAll

static void commitAll(BrokerTransactionalClient[] tx_clients) throws BrokerException

Commits the given list of open transactions. All work performed on these contexts will be finalized.











See also: abort()

deliver

void deliver(java.lang.String dest_id, BrokerEvent event) throws BrokerException

Deliver one event in the given transaction. Gives an event to the Broker to be given to the client with the given client ID. No exception is thrown if there is no client using the destination client ID. In addition to the listed exceptions, any communications exception can be thrown.

deliver

void deliver(java.lang.String dest_id, BrokerEvent[] events) throws BrokerException



BrokerNullParameterException tx_clients is null.


BrokerInvalidClientException If the client has been destroyed or disconnected.

BrokerInvalidClientIdException If the destination ID includes invalid characters.

BrokerInvalidEventException If the event does not match its type definition.

BrokerNoPermissionException If the client does not have permission to publish the event type.

BrokerNullParameterException If event or dest_id are null.

BrokerUnknownEventTypeException If the event type for the event does not exist on the Broker.




Deliver multiple events on the given transaction. Gives an array of events to the Broker to have them all delivered to the client with the given client ID. Either all of the events or none of them are delivered. No exception is thrown if there is no client using the destination client ID. In addition to the listed exceptions, any communications exception can be thrown.

deliverAckReplyEvent

void deliverAckReplyEvent(BrokerEvent request_event, long publish_seqn) throws BrokerException

Delivers an Adapter::ack event to the originator of the specified event, which is most likely a request event for given transaction. Properly sets the tag, track-Id, business-Context and activation envelope fields to match that of the request. Properly uses the reply-To envelope field if set. Set publish_seqn to zero (0) when not using publish sequence numbers in your application. In addition to the listed exceptions, any communications exception can be thrown.




BrokerInvalidEventException If any of the events does not match its type definition.

BrokerNoPermissionException If the client does not have permission to publish all of the event types.

BrokerNullParameterException If dest_id or events are null, or if any element in the array is null.

BrokerUnknownEventTypeException If the event type for any of the events does not exist on the Broker.



BrokerInvalidEventException If the event was not received from the Broker.

BrokerNoPermissionException If the client does not have permission to publish the Adapter::ack event type.

BrokerNullParameterException If request_event is null.



deliverErrorReplyEvent

void deliverErrorReplyEvent(BrokerEvent request_event, BrokerEvent error_event) throws BrokerException

Give a single error event to the Broker to all be delivered to the client that published the request_event for given transaction. No exception is thrown if there is no client using the destination client ID. Properly sets the tag, track-Id, activation, business-Context, app-Seqn, and app-Last-Seqn envelope fields. Properly uses the errors-To envelope field, if set. In addition to the listed exceptions, any communications exception can be thrown.

deliverNullReplyEvent

void deliverNullReplyEvent(BrokerEvent request_event, java.lang.String reply_event_type_name, long publish_seqn) throws BrokerException

Delivers a null event of type 'reply_event_type_name' to the originator of the specified event, which is most likely a request event for given transaction. Properly sets envelope tag, track-Id, activation, business-Context, app-Seqn, and app-Last-Seqn fields to indicate that this event is a null event. Properly uses the reply-To envelope field, if set. Null events are used to indicate that a request was successful and resulted in no data. Set publish_seqn to zero (0) when not using publish sequence numbers in your application. In addition to the listed exceptions, any communications exception can be thrown.



BrokerInvalidEventException If the request event was not received from the Broker, or the reply event does not match its event type.

BrokerNoPermissionException If the client does not have permission to publish the reply event type.

BrokerNullParameterException If request_event or error_event are null.

BrokerUnknownEventTypeException If the event type for the reply event does not exist on the Broker.



BrokerInvalidEventException If the event was not received from the Broker.




deliverPartialReplyEvents

int deliverPartialReplyEvents(BrokerEvent request_event, BrokerEvent[] events, int flag, int token) throws BrokerException

Give multiple events to the Broker to all be delivered to the client that published the 'request_event' for the given transaction. No exception is thrown if there is no client using the destination client ID. Either all of the events or none of them are delivered. Properly sets the tag, track-Id, activation, business-Context, app-Seqn, and app-Last-Seqn envelope fields. Properly uses the reply-To envelope field, if set. This function is used to deliver parts of a set of replies in groups.

When called the first time, 'flag' should be REPLY_FLAG_START. After doing this, additional calls can be made with other flag values. During intermediate replies, 'flag' should be REPLY_FLAG_CONTINUE. On the final call, 'flag' should be REPLY_FLAG_END. Calling this function with 'flag' as REPLY_FLAG_START_AND_END allows the entire result to be passed to this function in one call. The 'token' parameter is ignored on REPLY_FLAG_START and REPLY_FLAG_START_AND_END. On other calls, the return value from the previous call should be passed. The return value exists to carry information between calls and has no meaning to the caller. In addition to the listed exceptions, any communications exception can be thrown.

BrokerNullParameterException If request_event or reply_event_type_name are null.




BrokerInvalidEventException If the request event was not received from the Broker, or any of the reply events does not match its event type.

BrokerNoPermissionException If the client does not have permission to publish all of the reply events.

BrokerNullParameterException If request_event or events are null, or if any element in the events array is null.

BrokerOutOfRangeException If flag is not a valid value.

BrokerUnknownEventTypeException If the event type for any of the reply events does not exist on the Broker.




deliverReplyEvent

void deliverReplyEvent(BrokerEvent request_event, BrokerEvent event) throws BrokerException

Give a single event to the Broker to all be delivered to the client that published the 'request_event' for the given transaction. No exception is thrown if there is no client using the destination client ID. Properly sets the tag, track-Id, activation, business-Context, app-Seqn, and app-Last-Seqn envelope fields. Properly uses the reply-To envelope field, if set. In addition to the listed exceptions, any communications exception can be thrown.

deliverReplyEvents

void deliverReplyEvents(BrokerEvent request_event, BrokerEvent[] events) throws BrokerException

Give multiple events to the Broker to all be delivered to the client that published the 'request_event' for given transaction. No exception is thrown if there is no client using the destination client ID. Either all of the events or none of them are delivered. Properly sets the tag, track-Id, activation, business-Context, app-Seqn, and app-Last-Seqn envelope fields. Properly uses the reply-To envelope field, if set. In addition to the listed exceptions, any communications exception can be thrown.



BrokerInvalidEventException If the request event was not received from the Broker, or the reply event does not match its event type.


BrokerNullParameterException If request_event or event are null.




BrokerInvalidEventException If the request event was not received from the Broker, or any of the reply events does not match its event type.

BrokerNoPermissionException If the client does not have permission to publish all of the reply events.

BrokerNullParameterException If request_event or events are null, or if any element in the events array is null.



deliverWithAck

void deliverWithAck(java.lang.String dest_id, BrokerEvent[] events, int ack_type, long[] ack_seqn) throws BrokerException

Deliver multiple events on the given transaction. Gives an array of events to the Broker to have them all delivered to the client with the given client ID. Either all of the events or none of them are delivered. No exception is thrown if there is no client using the destination client ID. In addition to the listed exceptions, any communications exception can be thrown.

getEvent

public BrokerEvent getEvent(int msecs) throws BrokerException

Gets a single event from this client's queue, that is part of the given open transaction context. Blocks for a given number of milliseconds then gives up. If msecs is TIME_INFINITE (-1), it waits forever. If msecs is SYNCHRONOUS (-2), it returns immediately with either events, or null if no events are available. Acknowledges all events which have been retrieved previously that were not explicitly acknowledged.

BrokerUnknownEventTypeException If the event type for any of the reply events does not exist on the Broker.






BrokerNullParameterException If dest_id or events are null, or if any element in the array is null.

BrokerOutOfRangeException If the ack_type is not a legal ACK_* value.



If ack_seqn is not a valid event to acknowledge. Events are not published.




Note: Use caution when simultaneously calling this method from the same client on multiple threads. An event received on one thread might be acknowledged by another thread. To insure proper acknowledgement handling in this situation, use getEvents(int, long, int). For more information, see getEvents on page 396.


getEvents

public BrokerEvent[] getEvents(int max_events, int msecs) throws BrokerException

Gets one or more events from this client's queue, that is a part of the give open transaction context. Blocks for a given number of milliseconds then gives up. If msecs is TIME_INFINITE (-1), it waits forever. If msecs is SYNCHRONOUS (-2), it returns immediately with either events, or an array length of zero if no events are available.

Acknowledges all events which have been retrieved previously that were not explicitly acknowledged.

Note: Use caution when simultaneously calling this method from the same client on multiple threads. An event received on one thread might be acknowledged by another thread. To insure proper acknowledgement handling in this situation, use getEvents(int, long, int). For more information, see getEvents on page 397.

The number of events being returned is not guaranteed to be max_events even if there are more than many events in the client's queue. Any number of events up to the value of max_events can be returned. In addition to the listed exceptions, any communications exception can be thrown.


BrokerInterruptedException If interrupt-Get-Events is used to stop the call.


BrokerOutOfRangeException If msecs is less than -1.

BrokerTimeoutException If the timeout is reached before an event arrives.




BrokerOutOfRangeException If msecs is less than -1, or max_events is less than zero.



getEvents

public BrokerEvent[] getEvents(int max_events, long seqn, int msecs) throws BrokerException

This request gets processed only after the Broker-Transactional-Client is committed. If the given transaction is aborted this request will not be processed. The sequence number seqn is the event to acknowledge through. A value of zero acknowledges all events. A value of DO_NOT_ACK (-1) will not acknowledge any events. Gets one or more events from this client's queue. Blocks for a given number of milliseconds then gives up. If msecs is TIME_INFINITE (-1), it waits forever. If msecs is SYNCHRONOUS (-2), it returns immediately with either events, or an array length of zero if no events are available. Acknowledges all events which have been retrieved previously that were not explicitly acknowledged.

Note: Use caution when simultaneously calling this method from the same client on multiple threads. An event received on one thread might be acknowledged by another thread.

The number of events being returned is not guaranteed to be max_events even if there are more than many events in the client's queue. Any number of events up to the value of max_events can be returned. In addition to the listed exceptions, any communications exception can be thrown.

getExternalId

java.lang.String getExternalId()

Used by the application or an external manager to identify the context. It is a set when the context is created and remains constant for the life of the context. The external identifier is optional, it need not be unique, and can be null. Returns the identifier.

See Also: getId()

BrokerTimeoutException If the timeout is reached before any events arrive.




BrokerOutOfRangeException If msecs is less than -1, or max_events is less than zero, or seqn is less than -1.

BrokerTimeoutException If the timeout is reached before any events arrive.




getId

long getId()

Used by the Broker to identify the context. It is a globally unique identifier and remains constant for the life of the context. Returns the identifier.

See Also: getManagerId()

getState

int getState() throws BrokerException

Returns the state of the transaction.

getXAResource

BrokerXAResource getXAResource()

Returns an XAResource object that a transaction manager will use to manage this BrokerTransactionalClient's participation in a JTA distributed transaction.

For information about JTA transactions, see Sun's Java Transaction API and The XA Specification (PDF) from The Open Group.

interruptGetEvents

public void interruptGetEvents() throws BrokerException

Interrupt the current getEvent call for the client. If there is no such call in progress, the next such call is interrupted. This operation is intended for use in multi-threaded clients.

newOrReconnect

public static BrokerClient newOrReconnect( java.lang.String broker_host, java.lang.String broker_name,

Description copied from class BrokerClient

Overrides: interruptGetEvents in class BrokerClient




BrokerTxClosedException Transaction which has been either committed or aborted.



java.lang.String client_id, java.lang.String client_group, java.lang.String app_name, BrokerConnectionDescriptor desc) throws BrokerException

Attempts to create the Broker client. If the creation fails because the client already exists, then it reconnects to the client instead. broker_name can be null to request the default Broker. desc can be null to request a default connection. The state sharing flag in the descriptor is ignored if the client already exists. Whether or not the client shares state can only be set when making a new client. The returned BrokerClient needs to be typecasted to work with transactions.

newOrReconnectTransactionalClient

static BrokerTransactionalClient newOrReconnectTransactionalClient( java.lang.String broker_host, java.lang.String broker_name, java.lang.String client_id, java.lang.String client_group,



BrokerCommFailureException Problems occur establishing the connection.

BrokerHostNotFoundException The specified host does not exist.



BrokerNotRunningException The host exists but no Broker is running on that host.

BrokerNullParameterException broker_host, client_id, client_group, or app_name are null.

BrokerSecurityException A secure connection is attempted but is rejected by the Broker.

BrokerUnknownBrokerNameException The specified Broker does not exist. If broker_name is null, this indicates that there is no default Broker.

BrokerUnknownClientGroupException The specified client group does not exist on the Broker.

BrokerUnknownClientIdException The specified client ID does not exist on the Broker.



java.lang.String app_name, BrokerConnectionDescriptor desc) throws BrokerException

Attempts to create the client. If the creation fails because the client already exists, then it reconnects to the client instead. broker_name can be null to request the default Broker. desc can be null to request a default connection. The state sharing flag in the descriptor is ignored if the client already exists. Whether or not the client shares state can only be set when making a new client.

prepare

int prepare(String external_id) throws BrokerException


BrokerClientContentionException If the client ID is already in use by another client. For shared state clients, this means the maximum number of reconnects has been exceeded.



BrokerInvalidClientIdException If the ID contains illegal characters.



BrokerNullParameterException If broker_host, client_id, client_group, or app_name are null.


BrokerUnknownBrokerNameException If the specified Broker does not exist. If broker_name is null, this indicates that there is no default Broker.

BrokerUnknownClientGroupException If the specified client group does not exist on the Broker.

BrokerUnknownClientIdException If the specified client ID does not exist on the Broker.



Prepares the transaction with the specified external_id for commit. If prepare fails, you can only abort the transaction. You can recover a prepared transaction by calling recover. Calling prepare method is optional. You can directly commit or abort a transaction without preparing the transaction.

prepare

int prepare(long tx_id) throws BrokerException

Prepares the transaction with the specified Broker transaction ID for commit. If prepare fails, you can only abort the transaction. You can recover a prepared transaction by calling recover. Calling prepare method is optional. You can directly commit or abort a transaction without preparing the transaction.

prepareAll

static void prepareAll(BrokerTransactionalClient[] tx_clients, String external_id throws BrokerException

Prepares the transactions of tx_clients that have the specified external_id for commit. If prepareAll fails, you can only abort the transactions. You can recover prepared transactions by calling recover. Calling prepareAll method is optional. You can directly commit or abort transactions without preparing the transactions.

external_id A user defined, externally generated transaction identifier.


BrokerInvalidTxException The specified transaction does not exist.

BrokerNullParameterException Theexternal_id is null.

tx_id An unique Broker transaction identifier returned by the beginTransaction method.



BrokerNullParameterException Thetx_id is null.

tx_clients List of Broker transactional clients.

external_id Externally generated transaction identifier.



prepareAll

static void prepareAll(BrokerTransactionalClient tx_client String[] external_ids throws BrokerException

Prepares the transactions of the tx_client Broker transactional client that have the specified external_ids for commit. If prepareAll fails, you can only abort the transactions. You can recover prepared transactions by calling recover. Calling the prepareAll method is optional. You can directly commit or abort transactions without preparing the transactions.

publish

void publish(BrokerJMSEvent event) throws BrokerException

Publish one event with the given transaction id. The event is given to the Broker to be given to all subscribing clients. In addition to the listed exceptions, any communications exception can be thrown.



BrokerNullParameterException Theexternal_id or tx_clients is null.

tx_client Broker transactional client.

external_ids List of externally created transaction identifiers.



BrokerNullParameterException Theexternal_id or tx_clients is null.

Overrides: publish in class BrokerClient



BrokerInvalidEventException If the event does not match its type definition.

BrokerNoPermissionException If the client does not have permission to publish the event type.



publish

void publish(BrokerEvent[] events) throws BrokerException

Publish multiple events on the given transaction. Gives an array of events to the Broker to be given to subscribing clients. Either all of the events or none of them are published. In addition to the listed exceptions, any communications exception can be thrown.

publishWithAck

void publishWithAck( BrokerEvent[] events, int ack_type, long[] ack_seqn) throws BrokerException

Publish multiple events for the given transaction. Gives an array of events to the Broker to be given to subscribing clients. Either all of the events or none of them are published. In addition to the listed exceptions, any communications exception can be thrown.

BrokerNullParameterException If event is null.

BrokerUnknownEventTypeException If the event type for the event does not exist on the Broker.

Overrides: publish in class BrokerClient





BrokerNullParameterException If events is null, or if any element in the array is null.


Overrides: publishWithAck in class BrokerClient




reconnect

static BrokerTransactionalClient reconnect( java.lang.String broker_host, java.lang.String broker_name, java.lang.String client_id, BrokerConnectionDescriptor desc) throws BrokerException

Reconnects a client. broker_name can be null to request the default Broker. desc can be null to request a default connection. The state sharing flag in the descriptor is ignored by this call. Whether or not the client shares state can only be set when making a new client. For normal clients, only one active connection can be made to the Broker for a given client_id, so an error can be returned on reconnect if the client_id is already in use. For clients with shared state, multiple reconnects to the client_id can be made, but an error can be returned if the share limit is exceeded.





BrokerNullParameterException If events is null, or if any element in the array is null.

BrokerOutOfRangeException If the ack_type is not a legal ACK_* value.



If ack_seqn if not a valid event to acknowledge. Events are not published.








reconnectTransactionalClient

static BrokerTransactionalClient reconnectTransactionalClient( java.lang.String broker_host, java.lang.String broker_name, java.lang.String client_id, BrokerConnectionDescriptor desc) throws BrokerException

Reconnects a transactional client. broker_name can be null to request the default Broker. desc can be null to request a default connection. The state sharing flag in the descriptor is ignored by this call. Whether or not the client shares state can only be set when making a new client. For normal clients, only one active connection can be made to the Broker for a given client_id, so an error can be returned on reconnect if the client_id is already in use. For clients with shared state, multiple reconnects to the client_id can be made, but an error can be returned if the share limit is exceeded.


BrokerNullParameterException If broker_host or client_id are null.










BrokerNullParameterException If broker_host or client_id are null.




setId

protected void setId( long tx_id)

Used by the Broker to identify the context. It is a globally unique identifier and remains constant for the life of the context. Returns the identifier.

See Also: getManagerId()

BrokerTypeCache

class BrokerTypeCache extends java.lang.Object

This class provides methods to for managing the Broker type definitions stored in the application's local type definition cache.

For more information, see “Event Type Definition Cache” on page 155.

Methods

flushCache

static void flushCache( BrokerClient client) throws BrokerException

Flushes the type definition cache for the specified client and refreshes the cache from the Broker to which the Broker client is connected.

Throws BrokerInvalidClientException if client is not valid.




client The client whose type definition cache is to be flushed.




lockCache

static void lockCache()

Locks the local type definition cache so that it cannot be flushed.

unlockCache

static void unlockCache()

Unlocks the local type definition cache.

BrokerTypeDef

class BrokerTypeDef extends java.lang.Object

This class represents an event type definition. It provides methods for obtaining information on the Broker that manages the type definition. It also allows you to obtain information about the event type and its fields.

Constants






BrokerTypeDef Constants

Methods

getBaseTypeName

String getBaseTypeName()

Returns the base name of this event type. The base name does not have the event scope qualification.

See also: BrokerTypeDef.getDescription and BrokerTypeDef.getTypeName

getBrokerHost

String getBrokerHost()

Returns the host name of the Broker host where this event type is defined.

Name Description

short FIELD_TYPE_BOOLEAN Represents a boolean.

short FIELD_TYPE_BYTE Represents a byte.

short FIELD_TYPE_CHAR Represents a char.

short FIELD_TYPE_DATE Represents a BrokerDate.

short FIELD_TYPE_DOUBLE Represents a double.

short FIELD_TYPE_EVENT Represents a BrokerEvent.

short FIELD_TYPE_FLOAT Represents a float.

short FIELD_TYPE_INT Represents a int.

short FIELD_TYPE_LONG Represents a long.

short FIELD_TYPE_SEQUENCE Represents a sequence field.

short FIELD_TYPE_SHORT Represents a short.

short FIELD_TYPE_STRING Represents a string.

short FIELD_TYPE_STRUCT Represents a structure field.

short FIELD_TYPE_UNICODE_CHAR Represents a Unicode character.

short FIELD_TYPE_UNICODE_STRING Represents a Unicode String.

short FIELD_TYPE_UNKNOWN Represents a unknown field type.

int STORAGE_GUARANTEED Represent the guaranteed storage characteristic for event types.

int STORAGE_VOLATILE Represent the volatile storage characteristic for event types.



See also: BrokerTypeDef.getBrokerName and BrokerTypeDef.getBrokerPort

getBrokerName

String getBrokerName()

Returns the name of the Broker where this event type is defined.

See also: BrokerTypeDef.getBrokerHost and BrokerTypeDef.getBrokerPort

getBrokerPort

int getBrokerPort()

Returns the port number of the Broker Server where this event type is defined.

See also: BrokerTypeDef.getBrokerHost and BrokerTypeDef.getBrokerName

getDescription

String getDescription() throws BrokerException

Returns a string containing a description of this event type.

getFieldDef

BrokerTypeDef getFieldDef( String field_name) throws BrokerException

Returns the field type for the event field with the specified field_name. The field_name can directly identify any field in an event, no matter how deeply nested.

See also: BrokerTypeDef.getFieldType


BrokerInvalidTypeException The event is not valid.

field_name The name of a field within the event.


BrokerFieldNotFoundException The specified field_name does not exist in the event type.

BrokerFieldTypeMismatchException The field_name incorrectly accesses a type, such as using a subscript on a non-sequence field.




getFieldNames

String[] getFieldNames( String field_name) throws BrokerException

Returns field names for this event type. If field_name is null, all of the field names within the event are returned. Otherwise, field_name should refer to a field in a structure and this method returns all of the field names at that level. Note that field_name can directly identify any field in the event, no matter how deeply nested the fields might be. See “Specifying Field Names” on page 86 for more information.

getFieldType

short getFieldType( String field_name) throws BrokerException

Returns the field type of the field within this event, defined in “Constants” on page 407. If you request type information for a sequence field, this method will return FIELD_TYPE_SEQUENCE.

If you want to obtain the type of the elements contained in sequence, you can use this method with the field name like mySeq[]. See “Specifying Field Names” on page 86 for more information.

field_name The field name of a structure containing other fields. If set to null, all of the fields in the event are returned. See “Parameter Naming Rules” on page 419 for restrictions on event field names.





field_name The name of the field within the event whose type is to be returned. See “Parameter Naming Rules” on page 419 for restrictions on event field names.



See also: BrokerTypeDef.getDescription and BrokerTypeDef.getDescription

getScopeTypeName

String getScopeTypeName()

Returns the scope of this event type definition.

See also: BrokerTypeDef.getBaseTypeName and BrokerTypeDef.getTypeName

getStorageType

int getStorageType() throws BrokerException

Returns the storage type of this event type as one of the following STORAGE_* values defined in “Constants” on page 407.

getTerritoryName

String getTerritoryName()

Returns the territory name for the Broker where this event type is defined. Returns null if this object is not associated with any Broker.

See also: BrokerClient.getTerritoryName

getTimeToLive

int getTimeToLive() throws BrokerException

Returns the time, in seconds, that an event type will be available after being published before it expires or is destroyed. A return value of zero indicates the event will never expire.









getTypeName

String getTypeName()

Returns the fully qualified name of this event type definition. The fully qualified name consists of the base name with its scope qualifier.

See also: BrokerTypeDef.getFieldDef

toString

String toString()

Returns a string with information on this event type definition, suitable for display or printing.

toString

String toString( int indent_level)

Converts the event type definition into a string format that can be saved to a file.





A API Exceptions

This appendix describes the exceptions that can be thrown by the webMethods Broker Java API to report API, communications, and Broker failures.

You can use the BrokerException.toString method to obtain a character string that briefly describes the error associated with a particular BrokerException.

The BrokerException.toCompleteString method lets you obtain a character string that specifically describes the error associated with a particular BrokerException.

BrokerBadStateException An API call was made that conflicts with the current system state. For example:

You attempted to register a callback for a subscription ID before registering a general callback.

You attempted to invoke a second BrokerClient.dispatch while in a callback method.

BrokerClientContentionException An attempt was made to reconnect a Broker client, but the client is either already in use, or the client has shared state and the maximum number of shared clients has already been reached.

BrokerClientExistsExceptionThe client ID specified when creating a new BrokerClient is already is use.

BrokerCommFailureException A generic communications fault has occurred. Network failures cause this exception to be thrown.

BrokerConnectionClosedException The connection to the Broker closed before or during the operation you requested.

BrokerCorruptDataException The data object on which you are operating is corrupt. Currently only detected on BrokerEvent objects.

BrokerException This class is the base exception type for all exceptions thrown by Information Broker client classes. It refers to specific exception sub-class for information about why the exception is thrown.

BrokerFailureExceptionAn unexpected failure happened while the Broker was processing your request. This exception can have two possible meanings:

The API could not correctly process an exception into one of the other exceptions.

A Broker failure has occurred, such as running out of memory or a corrupted data store.


A API Exceptions

BrokerFieldNotFoundExceptionAn attempt was made to operate on a BrokerEvent field that does not exist.

BrokerFieldTypeMismatchExceptionThe specified event field is not of the expected type. For example, using the BrokerEvent.setStringField method on an event field of type int will cause this exception to be thrown.

BrokerFileNotFoundExceptionThe specified file could not be found or could not be opened.

BrokerFilterParseExceptionAn error occurred while parsing the filter string specified when creating a new BrokerFilter.

BrokerFilterRuntimeExceptionThe filter specified with the BrokerFilter.matchFilter method caused a runtime error, such as division by zero.

BrokerFormatExceptionThis can result from some protocol failures. It is mainly issued by the BrokerString calls to parse values out of strings.

BrokerHostNotFoundExceptionThe host specified when creating or reconnecting a BrokerClient could not be found.

BrokerIncompatibleVersionExceptionThe Broker is running an older version of the product than this API.

BrokerInterruptedExceptionA BrokerClient.getEvent or BrokerClient.getEvents method was interrupted by the invocation of the BrokerClient.interruptGetEvents method.

This exception can also be thrown if the BrokerClient.dispatch method was interrupted by a call to the BrokerClient.interruptDispatch method.

BrokerInvalidAcknowledgementExceptionAn attempt was made to acknowledge a sequence number that was out of order or which was not been assigned to your Broker client.

BrokerInvalidClassExceptionThe storage_class passed to the BrokerEvent constructor could not be instantiated using the class' newInstance method.

BrokerInvalidClientExceptionThe BrokerClient object passed to the method is either disconnected or has been destroyed.

BrokerInvalidClientIdExceptionThe client ID specified when creating a new BrokerClient contained illegal characters or was longer than 255 characters.

BrokerInvalidDescriptorExceptionThe BrokerConnectionDescriptor object passed to the method has been deleted.

BrokerInvalidEventExceptionThe BrokerEvent object passed to the method has been deleted.


A API Exceptions

BrokerInvalidEventTypeNameExceptionAn event type name contained illegal characters, reserved words, or has components over 255 characters in length. See “Parameter Naming Rules” on page 419 for information on valid event type names.

BrokerInvalidFieldNameExceptionA field name contains illegal characters, reserved words, or has components over 255 characters in length. See “Parameter Naming Rules” on page 419 for information on valid event type names.

BrokerInvalidPlatformKeyExceptionAn invalid platform key was specified.

BrokerInvalidSubscriptionExceptionA null event_type_name parameter, or a negative subscription ID parameter, or a filter string with a parse error were used when creating a new BrokerSubscription.

This exception can also be thrown if the subscription specified on BrokerClient.cancel was not found by the Broker.

BrokerInvalidTypeCacheExceptionAn internal error occurred with the event type definition cache. This does not represent a user error.

BrokerInvalidTypeDefExceptionThe BrokerTypeDef object passed to the method has been deleted. Either the client it was associated with was disconnected or destroyed, or the event type definition cache was flushed.

BrokerInvalidTypeExceptionAn attempt was made to set an event's field to a value that didn't match the field's type while using a method such as BrokerEvent.setField.

This exception can also be thrown when internal failures occur.

BrokerNoPermissionExceptionYou do not have the necessary permission to do the operation you attempted. For example:

Attempting to write to a read-only envelope field.

Using a client group that does not include your identity with the correct permissions when reconnecting or creating a new BrokerClient.

Attempting to publish an event type that is not allowed by your BrokerClient object's client group.

For more information on client group permissions and can publish permissions see Administering webMethods Broker.

BrokerNotImplementedExceptionThe method you requested is not implemented.


A API Exceptions

BrokerNotRunningExceptionWhile attempting to create or reconnect a BrokerClient, the specified host was found but no Broker was running on that host.

BrokerNullParamExceptionA null value was passed for a parameter that requires a value.

BrokerOutOfRangeExceptionA parameter value is outside the accepted range. For example, getting a sequence subset using negative indexes will cause this exception to be thrown.

BrokerPublishPauseExceptionAn internal failure occurred while communicating with the Broker.

BrokerProtocolExceptionAn internal failure occurred while communicating with the Broker.

BrokerSecurityExceptionA security problem occurred that prevented the operation from being completed.

BrokerSubscriptionExistsExceptionYou attempted to create a new BrokerSubscription with an event type and filter that has already been used for another subscription.

BrokerTimeoutExceptionThe requested operation timed out. This occurs for methods like BrokerClient.getEvent when an event is not received within the specified time-out interval.

BrokerTxClosedExceptionAction attempted on a BrokerClient transaction that has already been either committed or aborted.

BrokerUnknownBrokerNameExceptionThe Broker specified when reconnecting or creating a new BrokerClient was not found.

BrokerUnknownClientGroupExceptionThe client group specified when reconnecting or creating a new BrokerClient was not found.

BrokerUnknownClientIdExceptionThe Client ID specified when reconnecting a BrokerClient was not found.

BrokerUnknownEventTypeExceptionThe specified event type was not found on the Broker. This exception can be thrown, for example, if you attempt to create a new BrokerEvent with a non-existent type.

BrokerUnknownInfosetExceptionThe specified infoset was not found for the event type.

BrokerUnknownKeyExceptionThe platform specified key for BrokerClient.getPlatformInfo has no value defined.

BrokerUnknownNameExceptionThe specified distinguished name does not exist in the appropriate SSL certificate file.


A API Exceptions

BrokerUnknownTxExceptionSpecified name does not exist in the resource being accessed.


A API Exceptions


B Parameter Naming Rules

Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 420

Length Restriction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 420

Restricted Characters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 420

Reserved Words . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 421

System Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 421

webMethods Broker Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 421



Overview

This appendix describes the rules for naming webMethods Broker and system parameters, including host names, distinguished names, passwords, Broker names, and client group names as well as event type names and event field names.

Note: Unicode character values described in this section are represented as \u####.

Length Restriction

webMethods Broker uses a network data representation that requires all 2-byte unicode characters to be converted to 6 byte ANSI strings. Because the maximum parameter length is 255 bytes, this means that a parameter containing only Unicode characters cannot be any longer that 42 bytes. Each of the following webMethods Broker parameters must have a length of either 1 to 255 ANSI characters or 1 to 42 Unicode characters:

Broker name

Client group

Client ID

Event type name

Event field name

Infoset name

Infoset field name

Territory name

Restricted Characters

With a few restrictions, an webMethods Broker parameter can be specified using any Unicode or ANSI characters. This allows you to use a variety of languages when naming items such as a Broker or event type. However, some characters are restricted and cannot be used.

All non-printable ANSI characters (defined as the two ranges \u0000 to \u001F and \u007F to \u009F).

The ANSI characters '@', '/', and '\'.

Note: In addition to these restricted characters, specific types of webMethods Broker parameters can place further restrictions on allowable characters. See “webMethods Broker Parameters” on page 421 for complete details.



Reserved Words

EventType and Infoset Names

The name of an event type or infoset cannot be any of the words shown in “Reserved Words” on page 421 above or the table below. The entire event type or infoset name is checked against these two lists of reserved words. This means that you cannot use the name "broker" for an event type, but you can use the name "my::broker".

System Parameters

The table below shows common restrictions on system parameters, which depend on your specific platform.

webMethods Broker Parameters

The table below shows the restrictions placed on various webMethods Broker parameters.

any boolean byte char

const date double enum

false final float int

long null short string

struct true typedef unicode_char

unicode_string union unsigned

acl broker client clientgroup

event eventtype extends host

import infoset server

System Parameter Restrictions

Broker Host name Limited by most systems to printable 7-bit ASCII.

File names and Passwords

Limited by most systems to 8-bit ANSI characters.

Distinguished Names

Limited to printable 7-bit ASCII characters.



webMethods Broker Parameter Restrictions

Territory name

Broker name

Client Group name

Client Id

Cannot begin with a '#" or contain any of the restricted characters described in “Restricted Characters” on page 420.

Application name

Platform Info Key

Cannot contain any of the restricted characters described in “Restricted Characters” on page 420.

Event Type name

Event Field name

Infoset name

Infoset Field name

Cannot begin with a digit (0-9) or with an underscore. This can only contain alphanumeric characters, underscores, dollar symbols ('$'), and Unicode characters greater than \u009F. This cannot contain symbols, whitespace, and non-printable ANSI characters.

Platform Info value No restrictions.

Filter strings No restrictions, other than the syntax restrictions described in “Using Event Filters” on page 157.

Format strings No restrictions, but the '$', '{', and '}' characters are used as part of the format syntax.
