You are on page 1of 422

Title Page

webMethods Broker Client Java API


Programmers 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 20012011 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
webMethods Broker Client Java API Programmers Guide Version 8.2 3
Table of Contents
About this Guide . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
Document Conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
Documentation Installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
Online Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
1. Getting Started . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30
Event-Based Applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30
Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
Broker Clients . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
The Broker . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32
Broker-to-Broker Communication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32
Using the webMethods Broker Java API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33
Application Development with webMethods Broker . . . . . . . . . . . . . . . . . . . . . . . . . . . 33
Application Deployment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34
webMethods Broker Java API Online Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34
2. Using Broker Clients . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37
Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38
Understanding Broker Clients . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38
Client State . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38
Client Groups . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39
Client Life Cycle . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39
Queue Storage Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39
Client Infoset . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40
Creating and Destroying Broker Clients . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40
Client Identifiers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42
Assigning Client Identifiers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42
Obtaining Client Identifiers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42
Hard-coding Client Identifiers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42
Destroying a Broker Client . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43
Using Several Broker Clients . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43
Disconnecting and Reconnecting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43
Disconnecting a Broker Client . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44
Reconnecting a Broker Client . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44
Using the newOrReconnect Method . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45
Connection Notification . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46
Defining a Callback Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46
Registering the Callback Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46
Un-Registering Callback Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47
Obtaining Client State and Status . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47

4 webMethods Broker Client Java API Programmers Guide Version 8.2
Basic Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47
Client Queue Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48
Advanced Features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48
Connection Settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48
Client Time-out Settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48
Platform Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49
Broker Territory and Broker-to-Broker Communication . . . . . . . . . . . . . . . . . . . . . 49
Broker Connection Descriptors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49
Creating Connection Descriptors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50
Obtaining a Client's Connection Descriptor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50
Converting to String . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50
Automatic Re-connection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51
Using Automatic Re-connection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51
Rules for Automatic Re-connection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51
Using Client Keep-Alive . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52
Setting the Keep-Alive Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52
Getting the Current Keep-Alive Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53
Using the Keep-Alive Feature with a Shared Connection . . . . . . . . . . . . . . . . . . . 54
Sharing Connections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54
Sharing Client State . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54
Event Processing with Shared Client State . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55
By-Publisher Event Ordering . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55
Event Processing without Ordering . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56
When is Sharing State Useful? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56
State Sharing Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56
Calling Sequence for Sharing Client State . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56
Priority Ordering for Broker Queues . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57
Priority Ordering and Performance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57
Using Security Features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58
Redelivery Counting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58
3. Using the Callback Model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59
Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60
Understanding Callbacks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60
Using Callbacks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60
Implementing a Callback . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61
Passing Arguments to Callback Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61
General Callback Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62
Using General Callbacks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62
Specific Callback Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63
Using Specific Callbacks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63
Dispatching Callback Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64
Using dispatch . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64
Using mainLoop . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65
Using threadedCallbacks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65
webMethods Broker Client Java API Programmers Guide Version 8.2 5
Event Dispatching Rules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65
4. Creating and Initializing Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67
Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68
Event Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68
Event Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68
Event Type Cache . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69
Event Type Names . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69
Event Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70
Event Identifier . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70
Creating Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70
General Event Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71
Field Type Checking . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71
Converting Events as Binary Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72
Restoring Events from Binary Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72
Event Data Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72
Field Data Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72
Obtaining Field Names . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73
Regular Data Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73
Setting Regular Data Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73
Getting Regular Field Values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74
Sequence Data Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75
Setting Sequence Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76
Getting Sequence Field Values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77
Structure Data Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78
Setting Structure Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78
Setting a Struct Field from an Event . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78
Setting a Struct Sequence Field from an Event . . . . . . . . . . . . . . . . . . . . . . . . . . 79
Getting Structure Field Values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79
Getting a Struct Field as an Event . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79
Getting a Struct Sequence Field . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79
Envelope Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80
Read-only Envelope Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82
The connectionIntegrity Envelope Field . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84
The pubNetAddr Envelope Field . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85
The route Envelope Field . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85
Specifying Field Names . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86
5. Subscribing to and Receiving Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89
Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90
Event Subscriptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90
Limits on Subscriptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91
Subscribing to Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91
Uniqueness of Subscriptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91
Cancelling a Subscription . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92

6 webMethods Broker Client Java API Programmers Guide Version 8.2
Using Wildcards . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92
Receiving Events in the Get-Events Model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93
Getting Multiple Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93
Synchronous Get Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94
Detecting Redelivered Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95
Manual Redelivery Counting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 96
Automatic Redelivery Counting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97
Redelivery and Older Versions of webMethods Software . . . . . . . . . . . . . . . . . . . . . . . 98
Subscription Identifiers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99
Specifying Subscription IDs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99
Obtaining Subscription Identifiers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100
Generating Subscription Identifiers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100
BrokerSubscription Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101
Getting Events using the poll Method . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101
The BrokerClientPoll Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102
Key Methods used in the Polling Model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102
Using the poll Method . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102
A Polling Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103
Detecting Deadletters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104
Creating a Deadletter Subscription . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104
Deadletter Subscriptions and Filters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 105
Deadletter Permissions and Persistence . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 105
How Deadletter Subscriptions Relate to Regular Subscriptions . . . . . . . . . . . . . . 105
Deadletter Behavior in a Territory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 105
6. Using Request-Reply . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107
Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 108
The Request-Reply Model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 108
Request Events and the Tag Field . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 108
Getting and Setting the Tag . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109
Using the trackId Field . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109
Reply Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109
Determining a Reply Event's Type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109
The Requestor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 110
Using the Get-event Approach . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111
Callbacks with Tags . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112
Using publishRequestAndWait . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113
The Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114
Checking Subscription and Publishing Permissions . . . . . . . . . . . . . . . . . . . . . . . . . . . 115
Processing Request Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 116
Delivering Replies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117
Delivering Acknowledgment Replies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117
Delivering Error Replies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117
Delivering Null Replies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 118
Delivering One or More Reply Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 118
webMethods Broker Client Java API Programmers Guide Version 8.2 7
Delivering Partial Replies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 118
7. Transaction Semantics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121
Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122
About Transactional Client Processing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122
About the BrokerTransactionalClient Class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122
Transaction Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122
Using Broker Transaction Clients . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123
Obtaining an External Transaction ID . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 124
Beginning a Transaction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 124
Operating within a Transaction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 124
Publishing a Transaction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125
Publishing Multiple Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125
Delivering a Transaction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 126
Getting Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 126
Preparing Transactions For Commit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 127
Ending a Transaction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 127
Committing a Transaction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 128
Aborting a Transaction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 128
Destroying the Transactional Client . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 128
Creating a Transactional Client . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 129
8. Publishing and Delivering Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131
Publishing Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132
Limits on Publication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132
Publishing an Event . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 133
Publishing Multiple Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 133
Delivering Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 133
Obtaining the Client Identifier . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 134
Delivering an Event . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 134
Delivering Multiple Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 135
9. Handling Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 137
Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 138
BrokerExceptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 138
Catching Exceptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 138
Determining the Exception Type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 138
Getting an Exception Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 139
Setting the System Diagnostic Level . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 139
10. Using BrokerDate Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 141
Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 142
Date and Time Representation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 142
BrokerDate Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 142

8 webMethods Broker Client Java API Programmers Guide Version 8.2
11. Using Sequence Numbers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 145
Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 146
Sequence Numbers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 146
Publisher Sequence Numbers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 146
Using Publisher Sequence Numbers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 147
Maintaining Publish Sequence Number State . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 147
Receipt Sequence Numbers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 147
Default Acknowledgment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 148
Default Acknowledgment With Callbacks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 148
Explicitly Acknowledging Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 148
Maintaining Receipt Sequence Number State . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 149
Other Considerations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 149
12. Managing Event Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 151
Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 152
Event Type Definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 152
Obtaining Event Type Names . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 152
Obtaining Event Type Definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 153
Obtaining Event Field Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 153
Obtaining Event Type Descriptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 153
Obtaining Storage Type Property . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 153
Obtaining the Time-to-live Property . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 154
Obtaining Type Definitions as Strings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 154
Obtaining Broker Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 154
Broker Territory and Broker-to-Broker Communication . . . . . . . . . . . . . . . . . . . . . 155
Event Type Definition Cache . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 155
Notification of Event Type Definition Changes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 155
Locking the Type Definition Cache . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 155
Infosets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 156
13. Using Event Filters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 157
Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 158
Filter Strings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 158
Specifying Filter Strings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 158
Locale Considerations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 159
Filter Rules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 159
Field Names . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 159
Filter Operators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 160
Logical Filter Operators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 160
Comparison Filter Operators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 160
Arithmetic Filter Operators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 161
Bitwise Operators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 161
String Operators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 161
Operator Precedence . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 162
Using Regular Expressions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 163
webMethods Broker Client Java API Programmers Guide Version 8.2 9
Using Hints . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 163
Filter Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 164
charAt . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 164
contains . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 164
date . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 165
date . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 165
endsWith . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 165
regexpMatch . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 166
startsWith . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 166
substring . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 166
toDouble . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 167
toInt . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 167
toLong . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 167
toLowerCase . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 167
toString . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 168
toUpperCase . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 168
toUpperCase . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 168
Using Filters with Subscriptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 169
Using BrokerFilters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 169
Obtaining Filter Strings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 170
Obtaining Event Type Names . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 170
Converting Broker Filters to Strings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 171
14. Load Balancing and Failover for Publish Operations . . . . . . . . . . . . . . . . . . . . . . . . . . 173
Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 174
Understanding Clustering . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 174
BrokerClusterPublishers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 175
Monitoring Territory Activity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 175
Executing Publish/Deliver Operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 175
Load Balancing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 175
Publishers and Subscribers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 175
Failover . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 176
Using BrokerClusterPublisher . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 176
Creating and Destroying BrokerClusterPublisher . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 176
Creating a BrokerClientPublisher . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 177
Client Identifiers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 178
Obtaining Client Identifiers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 178
Destroying a BrokerClusterPublisher . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 178
Disconnecting and Reconnecting BrokerClusterPublisher . . . . . . . . . . . . . . . . . . . . . . 179
Disconnecting a BrokerClusterPublisher . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 179
Reconnecting a BrokerClusterPublisher . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 179
Using the newOrReconnect method . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 180
Broker Cluster Publisher Connection Notification . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 181
Defining a Connection Callback Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 181
Registering the Connection Callback Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 181

10 webMethods Broker Client Java API Programmers Guide Version 8.2
Canceling the Connection Callback Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 182
Broker Cluster Publisher Selection Notification . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 182
Defining a Selection Callback Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 183
Registering the Selection Callback Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 183
Canceling the Selection Callback Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 183
Obtaining BrokerClusterPublisher Status . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 185
Publishing and Delivering Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 185
Creating a New BrokerEvent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 186
Field Type Checking . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 186
Publishing Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 187
Publishing an Event . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 187
Publishing Multiple Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 188
Delivering Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 189
Delivering an Event . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 189
Delivering Multiple Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 190
Request-Reply Model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 190
Using publishRequestAndWait . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 190
Include-Exclude Brokers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 191
15. Working with Basic Authentication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 193
Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 194
Basic Authentication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 194
Configuring the Broker Java Client for Basic Authentication . . . . . . . . . . . . . . . . . . . . . . . . 194
Configuring Basic Authentication by using BrokerConnectionDescriptor Class . . . . . . 194
Configuring Basic Authentication by Using System Properties . . . . . . . . . . . . . . . . . . . 195
16. Working with SSL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 197
Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 198
Broker SSL Security . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 198
Certificate Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 198
Configuring the Broker Java Client for SSL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 199
Configuring SSL Using the BrokerConnectionDescriptor Class . . . . . . . . . . . . . . . . . . 199
Configuring SSL by Using the System Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . 201
Setting Encryption . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 201
Retrieving a Broker Server's Certificate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 202
Enabling FIPS in Java Clients . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 202
17. Java API Client Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 203
BrokerCallback . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 203
handleBrokerEvent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 204
BrokerClient . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 204
Constants . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 204
Constructor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 206
BrokerClient . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 206
Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 209
acknowledge Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 209
webMethods Broker Client Java API Programmers Guide Version 8.2 11
acknowledge . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 209
acknowledge . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 209
acknowledgeThrough . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 210
begin Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 210
beginAdapterTransaction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 210
beginTransaction (deprecated) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 211
can Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 212
canPublish . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 212
canSubscribe . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 212
cancel Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 213
cancelCallbackForSubId . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 213
cancelCallbackForTag . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 213
cancelCallbacks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 214
cancelCheckForEvents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 214
cancelSubscription . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 214
cancelSubscription . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 215
cancelSubscriptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 215
check Method . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 216
checkForEvents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 216
clear Method . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 217
clearQueue . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 217
create Method . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 217
createClientQueueBrowser . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 217
deliver Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 218
deliver . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 218
deliver . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 219
deliverAckReplyEvent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 220
deliverErrorReplyEvent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 220
deliverNullReplyEvent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 221
deliverPartialReplyEvents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 222
deliverReplyEvent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 224
deliverReplyEvents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 224
deliverRequestAndWait . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 225
deliverWithAck . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 226
destroy Method . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 228
destroy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 228
disconnect Method . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 228
disconnect . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 228
dispatch Method . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 229
dispatch . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 229
does Method . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 230
doesSubscriptionExist . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 230
end Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 230
endAdapterTransaction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 230
endTransaction (deprecated) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 231

12 webMethods Broker Client Java API Programmers Guide Version 8.2
finalize Method . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 232
finalize . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 232
get Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 232
getAccessLabel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 232
getApiVersionNumber . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 232
getApplicationName . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 232
getBrokerHost . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 233
getBrokerName . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 233
getBrokerPort . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 233
getBrokerSSLCertificate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 233
getBrokerVersionNumber . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 234
getCanPublishNames . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 234
getCanPublishTypeDefs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 234
getCanSubscribeNames . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 234
getCanSubscribeTypeDefs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 235
getClientGroup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 235
getClientId . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 235
getClientInfoset . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 235
getClientSSLEncryptionLevel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 236
getConnectionDescriptor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 236
getDefaultBrokerPort . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 236
getEvent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 236
getEvents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 238
getEvents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 239
getEventTypeDef . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 240
getEventTypeDefs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 241
getEventTypeInfoset . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 241
getEventTypeInfosetNames . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 242
getEventTypeInfosets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 243
getEventTypeNames . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 243
getEventTypeNames . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 244
getLastPublishSequenceNumber . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 244
getPlatformInfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 244
getPlatformInfoKeys . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 245
getQueueLength . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 245
getRetrievedStatus . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 246
getRetrievedSessionID . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 246
getScopeNames . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 246
getStateShareLimit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 246
getSubscriptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 247
getTerritoryName . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 247
increment Method . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 247
incrementRedeliveryCount . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 247
interrupt Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 248
interruptDispatch . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 248
webMethods Broker Client Java API Programmers Guide Version 8.2 13
interruptGetEvents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 248
interruptCheckForEvents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 248
is Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 249
isClientPending . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 249
isConnected . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 249
isPending . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 249
main Method . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 250
mainLoop . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 250
make Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 250
makeSubId . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 250
makeTag . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 250
makeTransactionId . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 251
makeUniqueSubId . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 251
negative Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 251
negativeAcknowledge . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 251
negativeAcknowledge . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 252
new Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 253
newOrReconnect . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 253
newSubscription . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 254
newSubscription . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 255
newSubscription . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 257
newSubscriptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 257
poll Method . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 258
poll . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 258
prime Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 259
prime . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 259
primeAllClients . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 260
publish Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 260
publish . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 260
publish . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 261
publishRequestAndWait . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 261
publishWithAck . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 262
reconnect Method . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 264
reconnect . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 264
register Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 266
registerCallback . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 266
registerCallbackForSubId . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 266
registerCallbackForTag . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 267
registerConnectionCallback . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 268
resend Method . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 269
resendUnacknowledgedEvents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 269
set Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 270
setAutomaticControlLabel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 270
setClientInfoset . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 270
setDefaultClientTimeout . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 270

14 webMethods Broker Client Java API Programmers Guide Version 8.2
setPlatformInfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 271
setStateShareLimit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 271
stop Method . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 272
stopMainLoop . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 272
threaded Method . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 272
threadedCallbacks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 272
to Method . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 273
toString . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 273
BrokerClientPoll . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 273
Constants . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 273
Constructors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 274
BrokerClientPoll . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 274
Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 275
getBrokerClient . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 275
getData . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 275
getReady . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 275
getRequested . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 275
isReady . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 276
isRequested . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 276
setData . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 276
BrokerClusterPublisher . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 277
Constructor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 277
BrokerClusterPublisher . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 277
Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 278
cancelConnectionCallback . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 278
cancelSelectionCallback . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 279
canPublish . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 279
deliver . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 279
deliver . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 280
deliverRequestAndWait . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 281
destroy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 282
disconnect . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 282
excludeBroker . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 283
getApplicationName . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 283
getCanPublishNames . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 283
getClientGroup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 284
getClientId . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 284
getClusterPublisherInfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 284
getClusterPublisherStats . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 284
getLastUsed . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 285
getMonitorClientId . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 285
getTerritoryName . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 286
includeBroker . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 286
isConnected . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 286
localPublish . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 286
webMethods Broker Client Java API Programmers Guide Version 8.2 15
localPublish . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 287
localPublishRequestAndWait . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 288
newOrReconnect . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 288
publish . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 290
publish . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 291
publishRequestAndWait . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 291
reconnect . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 292
registerConnectionCallback . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 294
registerSelectionCallback . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 294
toString . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 295
BrokerConnectionCallback . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 295
Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 295
handleConnectionChange . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 295
BrokerConnectionDescriptor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 296
Constants . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 297
Constructor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 298
BrokerConnectionDescriptor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 298
BrokerConnectionDescriptor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 298
Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 298
getAccessLabelHint . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 298
getAuthUserName . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 299
getAutomaticReconnect . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 299
getAutomaticRedeliveryCount . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 299
getConnectionShare . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 299
getConnectionShareLimit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 299
getForcedReconnect . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 300
getKeepAlivePeriod . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 300
getKeepAliveResponseTime . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 300
getKeepAliveRetryCount . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 301
getRedeliveryCountEnabled . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 301
getSharedEventOrdering . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 301
getSSLCertificate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 302
getSSLCertificateDns . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 303
getSSLCertificateFile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 303
getSSLCipherSuites . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 304
getSSLDistinguishedName . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 304
getSSLEncrypted . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 304
getSSLEncryptionLevel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 304
getSSLKeystore . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 305
getSSLKeystoreType . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 305
getSSLKeystoreType . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 305
getSSLProvider . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 305
getSSLTruststoreType . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 305
getSSLRootDns . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 305
getStateShare . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 306

16 webMethods Broker Client Java API Programmers Guide Version 8.2
setAccessLabelHint . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 306
setAuthInfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 306
setAutomaticReconnect . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 307
setAutomaticRedeliveryCount . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 307
setConnectionShare . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 307
setConnectionShareLimit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 308
setForcedReconnect . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 308
setKeepAlive . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 308
setRedeliveryCountEnabled . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 310
setSharedEventOrdering . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 310
setSSLCertificate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 311
setSSLCipherSuites . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 312
setSSLEncrypted . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 312
setSSLProvider . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 312
setSSLKeystore . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 313
setSSLKeystoreType . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 313
setSSLTruststore . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 313
setSSLTruststoreType . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 313
setStateShare . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 313
toString . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 313
BrokerCPConnectionCallback . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 314
Method . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 314
handleConnectionChange . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 314
BrokerCPSelectionCallback . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 314
Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 315
chooseClusterClient . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 315
chooseClusterClient . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 315
BrokerDate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 316
Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 316
Constructors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 316
BrokerDate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 316
BrokerDate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 316
BrokerDate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 317
BrokerDate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 317
BrokerDate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 317
BrokerDate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 317
BrokerDate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 317
BrokerDate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 318
Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 319
clear . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 319
clearTime . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 319
compareTo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 319
equals . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 319
getJavaCalendar . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 319
getJavaDate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 320
webMethods Broker Client Java API Programmers Guide Version 8.2 17
parseDate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 320
parseLocalizedDate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 321
setDate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 321
setDateTime . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 322
setJavaCalendar . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 322
setJavaDate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 323
setTime . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 323
toLocalizedString . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 323
toString . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 323
toString . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 324
BrokerEvent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 324
Constants . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 324
Constructors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 325
BrokerEvent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 325
BrokerEvent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 326
BrokerEvent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 327
BrokerEvent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 328
Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 329
clear . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 329
clearField . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 329
clearModificationFlag . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 330
fromBinData . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 330
fromObject . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 331
get<type>Field . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 331
get<type>SeqField . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 333
getBaseTypeName . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 334
getBooleanField . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 335
getBooleanSeqField . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 335
getByteField . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 335
getByteSeqField . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 335
getCharField . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 335
getCharSeqField . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 335
getClient . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 335
getDateField . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 335
getDateSeqField . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 335
getDoubleField . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 335
getDoubleSeqField . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 335
getEventId . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 335
getField . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 336
getFieldNames . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 336
getFieldType . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 337
getFloatField . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 338
getFloatSeqField . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 338
getIntegerField . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 338
getIntegerSeqField . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 338

18 webMethods Broker Client Java API Programmers Guide Version 8.2
getLongField . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 338
getLongSeqField . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 338
getPriority . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 338
getPublishSequenceNumber . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 338
getReceiptSequenceNumber . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 339
getScopeTypeName . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 339
getSequenceField . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 339
getSequenceFieldSize . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 340
getShortField . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 341
getShortSeqField . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 341
getStorageObject . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 341
getStringField . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 341
getStringSeqField . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 341
getStructFieldAsEvent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 341
getStructSeqFieldAsEvents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 342
getSubscriptionIds . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 343
getRedeliveryCount . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 343
getTag . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 344
getTypeDef . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 344
getTypeName . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 344
getUCCharField . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 344
getUCCharSeqField . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 344
getUCStringField . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 345
getUCStringSeqField . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 345
hasBeenModified . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 345
isAckReply . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 345
isErrorReply . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 345
isFieldSet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 345
isLastReply . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 346
isNullReply . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 346
set<type>Field . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 346
set<type>SeqField . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 348
setBooleanField . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 349
setBooleanSeqField . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 349
setByteField . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 349
setByteSeqField . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 350
setCharField . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 350
setCharSeqField . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 350
setDateField . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 350
setDateSeqField . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 350
setDoubleField . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 350
setDoubleSeqField . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 350
setField . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 350
setField . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 351
setFloatField . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 352
webMethods Broker Client Java API Programmers Guide Version 8.2 19
setFloatSeqField . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 353
setIntegerField . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 353
setIntegerSeqField . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 353
setLongField . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 353
setLongSeqField . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 353
setModificationFlag . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 353
setPriority . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 353
setPublishSequenceNumber . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 353
setSequenceField . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 354
setSequenceFieldSize . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 356
setShortField . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 356
setShortSeqField . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 357
setStringField . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 357
setStringFieldToSubstring . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 357
setStringSeqField . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 357
setStructFieldFromEvent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 358
setStructSeqFieldFromEvents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 358
setTag . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 359
setUCCharField . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 359
setUCCharSeqField . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 360
setUCStringField . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 360
setUCStringFieldToSubstring . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 360
setUCStringSeqField . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 361
stringFromANSI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 361
stringToANSI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 361
toBinData . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 361
toFormattedString . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 361
toFormattedString . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 362
toLocalizedFormattedString . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 362
toLocalizedString . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 362
toObject . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 363
toString . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 363
toString . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 363
toString . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 364
toString . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 364
validate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 364
BrokerException . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 365
Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 365
getCode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 365
getDiagnostics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 365
getMessage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 365
getMinorCode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 366
setDiagnostics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 366
toCompleteString . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 366
toString . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 366

20 webMethods Broker Client Java API Programmers Guide Version 8.2
BrokerField . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 367
Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 367
type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 367
value . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 367
Constructors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 367
BrokerField . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 367
BrokerField . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 367
BrokerFilter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 367
Constructors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 368
BrokerFilter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 368
BrokerFilter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 368
Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 369
getEventTypeName . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 369
getFilterString . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 369
match . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 369
toString . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 370
BrokerFormat . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 370
Specifying Field Names and Formats . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 370
Format options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 371
Constructor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 371
BrokerFormat . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 371
Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 372
assemble . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 372
assemble . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 372
assemble . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 373
format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 373
format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 373
format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 373
format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 374
format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 374
formatBindVariable . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 375
getTokenCount . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 375
getTokenValue . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 375
isReferenceToken . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 376
preparse . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 376
setFormatMode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 376
BrokerMonitorClient . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 377
Constructors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 377
BrokerMonitorClient . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 377
Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 378
destroy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 378
getHostName . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 378
getPort . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 378
getServerLogEntries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 378
getServerLogStatus . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 379
webMethods Broker Client Java API Programmers Guide Version 8.2 21
getServerRunStatus . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 379
getServers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 379
getVersion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 379
getVersionNumber . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 379
pruneMonitorLog . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 380
reloadConfig . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 380
reloadConfigForServer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 380
startServer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 380
toString . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 381
BrokerSSLCertificate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 381
Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 381
begin_date . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 381
distinguished_name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 381
end_date . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 381
issuer_distinguished_name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 381
status . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 382
Constructors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 382
BrokerSSLCertificate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 382
BrokerSSLCertificate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 382
BrokerSubscription . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 382
Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 383
event_type_name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 383
filter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 383
sub_id . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 383
Constructors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 383
BrokerSubscription . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 383
BrokerSubscription . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 383
BrokerSubscription . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 384
Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 384
toString . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 384
BrokerTransactionalClient . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 384
Constructors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 385
BrokerTransactionalClient . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 385
Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 386
abort . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 386
abortAll . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 386
acknowledge . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 387
acknowledge . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 387
acknowledgeThrough . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 388
beginTransaction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 388
commit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 389
commitAll . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 389
deliver . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 390
deliver . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 390
deliverAckReplyEvent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 391

22 webMethods Broker Client Java API Programmers Guide Version 8.2
deliverErrorReplyEvent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 392
deliverNullReplyEvent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 392
deliverPartialReplyEvents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 393
deliverReplyEvent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 394
deliverReplyEvents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 394
deliverWithAck . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 395
getEvent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 395
getEvents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 396
getEvents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 397
getExternalId . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 397
getId . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 398
getState . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 398
getXAResource . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 398
interruptGetEvents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 398
newOrReconnect . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 398
newOrReconnectTransactionalClient . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 399
prepare . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 400
prepare . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 401
prepareAll . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 401
prepareAll . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 402
publish . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 402
publish . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 403
publishWithAck . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 403
reconnect . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 404
reconnectTransactionalClient . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 405
setId . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 406
BrokerTypeCache . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 406
Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 406
flushCache . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 406
lockCache . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 407
unlockCache . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 407
BrokerTypeDef . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 407
Constants . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 407
Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 408
getBaseTypeName . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 408
getBrokerHost . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 408
getBrokerName . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 409
getBrokerPort . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 409
getDescription . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 409
getFieldDef . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 409
getFieldNames . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 410
getFieldType . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 410
getScopeTypeName . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 411
getStorageType . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 411
getTerritoryName . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 411
webMethods Broker Client Java API Programmers Guide Version 8.2 23
getTimeToLive . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 411
getTypeName . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 412
toString . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 412
toString . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 412
A. API Exceptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 413
B. Parameter Naming Rules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 419
Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 420
Length Restriction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 420
Restricted Characters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 420
Reserved Words . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 421
EventType and Infoset Names . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 421
System Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 421
webMethods Broker Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 421

24 webMethods Broker Client Java API Programmers Guide Version 8.2

webMethods Broker Client Java API Programmers Guide Version8.2 25
About this Guide
The webMethods Broker Client Java API Programmers 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
26 webMethods Broker Client Java API Programmers Guide Version8.2

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
webMethods Broker Client Java API Programmers Guide Version8.2 27
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...
About this Guide
28 webMethods Broker Client Java API Programmers Guide Version8.2


webMethods Broker Client Java API Programmers Guide Version8.2 29
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
30 webMethods Broker Client Java API Programmers Guide Version8.2

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.
webMethods Broker Client Java API Programmers Guide Version8.2 31
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
32 webMethods Broker Client Java API Programmers Guide Version8.2

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.
webMethods Broker Client Java API Programmers Guide Version8.2 33
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
34 webMethods Broker Client Java API Programmers Guide Version8.2

4 Use Designer to define the events for your application. See the Software AG Designer
Online Help or your system administrator.
Note: Broker events are known as Broker document types in Designer.
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
webMethods Broker Client Java API Programmers Guide Version8.2 35
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
36 webMethods Broker Client Java API Programmers Guide Version8.2


webMethods Broker Client Java API Programmers Guide Version8.2 37
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
2 Using Broker Clients
38 webMethods Broker Client Java API Programmers Guide Version8.2

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.
webMethods Broker Client Java API Programmers Guide Version8.2 39
2 Using Broker Clients

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.
2 Using Broker Clients
40 webMethods Broker Client Java API Programmers Guide Version8.2

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.
webMethods Broker Client Java API Programmers Guide Version8.2 41
2 Using Broker Clients

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;
}
. . .
2 Using Broker Clients
42 webMethods Broker Client Java API Programmers Guide Version8.2

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
webMethods Broker Client Java API Programmers Guide Version8.2 43
2 Using Broker Clients

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
2 Using Broker Clients
44 webMethods Broker Client Java API Programmers Guide Version8.2

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 {
c = new BrokerClient(broker_host, broker_name, null,
client_group, "Publish Sample #1",null);
} catch (BrokerException ex) {
. . .
}
/* Save the client ID */
client_id = c.getClientId();
. . .
/* Disconnect the client */
try {
c.disconnect();
} catch (BrokerException ex) {
webMethods Broker Client Java API Programmers Guide Version8.2 45
2 Using Broker Clients

. . .
}
. . .
/* Reconnect the client with the same client_id */
try {
c = BrokerClient.reconnect(broker_host, broker_name,
client_id, null);
} catch (BrokerException ex) {
. . .
}
. . .
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);
} catch (BrokerException ex) {
. . .
}
/* Do some processing */
. . .
/* Disconnect the client */
try {
c.disconnect();
} catch (BrokerException ex) {
. . .
}
. . .
2 Using Broker Clients
46 webMethods Broker Client Java API Programmers Guide Version8.2

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.
webMethods Broker Client Java API Programmers Guide Version8.2 47
2 Using Broker Clients

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.
2 Using Broker Clients
48 webMethods Broker Client Java API Programmers Guide Version8.2

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.
webMethods Broker Client Java API Programmers Guide Version8.2 49
2 Using Broker Clients

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.
2 Using Broker Clients
50 webMethods Broker Client Java API Programmers Guide Version8.2

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.
webMethods Broker Client Java API Programmers Guide Version8.2 51
2 Using Broker Clients

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.
2 Using Broker Clients
52 webMethods Broker Client Java API Programmers Guide Version8.2

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:
webMethods Broker Client Java API Programmers Guide Version8.2 53
2 Using Broker Clients

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).
2 Using Broker Clients
54 webMethods Broker Client Java API Programmers Guide Version8.2

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.
webMethods Broker Client Java API Programmers Guide Version8.2 55
2 Using Broker Clients

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
2 Using Broker Clients
56 webMethods Broker Client Java API Programmers Guide Version8.2

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.
webMethods Broker Client Java API Programmers Guide Version8.2 57
2 Using Broker Clients

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.
2 Using Broker Clients
58 webMethods Broker Client Java API Programmers Guide Version8.2

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

webMethods Broker Client Java API Programmers Guide Version8.2 59
3 Using the Callback Model
Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60
Understanding Callbacks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60
General Callback Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62
Specific Callback Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63
Dispatching Callback Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64
3 Using the Callback Model
60 webMethods Broker Client Java API Programmers Guide Version8.2

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.
webMethods Broker Client Java API Programmers Guide Version8.2 61
3 Using the Callback Model

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.
3 Using the Callback Model
62 webMethods Broker Client Java API Programmers Guide Version8.2

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 */
. . .
webMethods Broker Client Java API Programmers Guide Version8.2 63
3 Using the Callback Model

/* 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 */
. . .
3 Using the Callback Model
64 webMethods Broker Client Java API Programmers Guide Version8.2

/* 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) {
System.out.println("Error on dispatch\n"+ex);
return;
}
. . .
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.
webMethods Broker Client Java API Programmers Guide Version8.2 65
3 Using the Callback Model

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.
3 Using the Callback Model
66 webMethods Broker Client Java API Programmers Guide Version8.2


webMethods Broker Client Java API Programmers Guide Version8.2 67
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
4 Creating and Initializing Events
68 webMethods Broker Client Java API Programmers Guide Version8.2

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.
Note: Broker events are known as Broker document types in Designer.
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.
webMethods Broker Client Java API Programmers Guide Version8.2 69
4 Creating and Initializing Events

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.
4 Creating and Initializing Events
70 webMethods Broker Client Java API Programmers Guide Version8.2

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 Programmers 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 */
. . .
webMethods Broker Client Java API Programmers Guide Version8.2 71
4 Creating and Initializing Events

/* 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.
4 Creating and Initializing Events
72 webMethods Broker Client Java API Programmers Guide Version8.2

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.
webMethods Broker Client Java API Programmers Guide Version8.2 73
4 Creating and Initializing Events

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
4 Creating and Initializing Events
74 webMethods Broker Client Java API Programmers Guide Version8.2

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
BrokerEvent Method Value Type
webMethods Broker Client Java API Programmers Guide Version8.2 75
4 Creating and Initializing Events

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.
BrokerEvent Method Value Type
getBooleanField boolean
getByteField byte
getCharField char
getDateField BrokerDate
getDoubleField double
getFloatField float
getIntegerField int
getLongField long
getShortField short
getStringField String
4 Creating and Initializing Events
76 webMethods Broker Client Java API Programmers Guide Version8.2

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[]
webMethods Broker Client Java API Programmers Guide Version8.2 77
4 Creating and Initializing Events

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[]
4 Creating and Initializing Events
78 webMethods Broker Client Java API Programmers Guide Version8.2

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
webMethods Broker Client Java API Programmers Guide Version8.2 79
4 Creating and Initializing Events

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.
4 Creating and Initializing Events
80 webMethods Broker Client Java API Programmers Guide Version8.2

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.
webMethods Broker Client Java API Programmers Guide Version8.2 81
4 Creating and Initializing Events

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.
Envelope Field Event Editor Type Description
4 Creating and Initializing Events
82 webMethods Broker Client Java API Programmers Guide Version8.2

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".
Envelope Field Event Editor Type Description
webMethods Broker Client Java API Programmers Guide Version8.2 83
4 Creating and Initializing Events

Envelope Field Event Editor Type Description
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.
connectionIntegri
ty
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.
pubDistinguishedN
ame
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.
4 Creating and Initializing Events
84 webMethods Broker Client Java API Programmers Guide Version8.2

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.
Envelope Field Event Editor Type Description
webMethods Broker Client Java API Programmers Guide Version8.2 85
4 Creating and Initializing Events

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
4 Creating and Initializing Events
86 webMethods Broker Client Java API Programmers Guide Version8.2

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
webMethods Broker Client Java API Programmers Guide Version8.2 87
4 Creating and Initializing Events

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
Field Name Description Related BrokerEvent Methods
4 Creating and Initializing Events
88 webMethods Broker Client Java API Programmers Guide Version8.2

structC[].seqD[][
]
Used to obtain the field's type
when the number of elements
in the sequences structC and
seqD are not known.
getFieldType
Field Name Description Related BrokerEvent Methods

webMethods Broker Client Java API Programmers Guide Version8.2 89
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
5 Subscribing to and Receiving Events
90 webMethods Broker Client Java API Programmers Guide Version8.2

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.
webMethods Broker Client Java API Programmers Guide Version8.2 91
5 Subscribing to and Receiving Events

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.
5 Subscribing to and Receiving Events
92 webMethods Broker Client Java API Programmers Guide Version8.2

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.
webMethods Broker Client Java API Programmers Guide Version8.2 93
5 Subscribing to and Receiving Events

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.
5 Subscribing to and Receiving Events
94 webMethods Broker Client Java API Programmers Guide Version8.2

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:
webMethods Broker Client Java API Programmers Guide Version8.2 95
5 Subscribing to and Receiving Events

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:
5 Subscribing to and Receiving Events
96 webMethods Broker Client Java API Programmers Guide Version8.2

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.
webMethods Broker Client Java API Programmers Guide Version8.2 97
5 Subscribing to and Receiving Events

. . .
/* -----------------------------------------------*/
/* 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";

5 Subscribing to and Receiving Events
98 webMethods Broker Client Java API Programmers Guide Version8.2

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.
webMethods Broker Client Java API Programmers Guide Version8.2 99
5 Subscribing to and Receiving Events

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) {
System.out.println("Error on create subscription #1\n"+ex);
return;
}
/* Make subscription #2*/
try {
c.newSubscription( 2, "Sample::SimpleEvent2",null);
} catch (BrokerException ex) {
System.out.println("Error on create subscription #2\n"+ex);
return;
}
. . .
5 Subscribing to and Receiving Events
100 webMethods Broker Client Java API Programmers Guide Version8.2

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 events 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.
webMethods Broker Client Java API Programmers Guide Version8.2 101
5 Subscribing to and Receiving Events

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.
5 Subscribing to and Receiving Events
102 webMethods Broker Client Java API Programmers Guide Version8.2

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.
webMethods Broker Client Java API Programmers Guide Version8.2 103
5 Subscribing to and Receiving Events

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

5 Subscribing to and Receiving Events
104 webMethods Broker Client Java API Programmers Guide Version8.2

/* ----- 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) {
System.out.println("Error on create subscription\n"+ex);
return;
}
. . .
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) {
System.out.println("Error on create subscription\n"+ex);
return;
}
. . .
The following code fragment show how you would use the wildcard character to create a
deadletter subscription for all events.
webMethods Broker Client Java API Programmers Guide Version8.2 105
5 Subscribing to and Receiving Events

BrokerClient c;
. . .
/* Create a deadletter subscription for all event types*/
try {
c.newSubscription("*","{hint:DeadLetterOnly})";
catch (BrokerException ex) {
System.out.println("Error on create subscription\n"+ex);
return;
}
. . .
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.
5 Subscribing to and Receiving Events
106 webMethods Broker Client Java API Programmers Guide Version8.2

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.

webMethods Broker Client Java API Programmers Guide Version8.2 107
6 Using Request-Reply
Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 108
The Request-Reply Model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 108
The Requestor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 110
The Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114
6 Using Request-Reply
108 webMethods Broker Client Java API Programmers Guide Version8.2

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.
webMethods Broker Client Java API Programmers Guide Version8.2 109
6 Using Request-Reply

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.
6 Using Request-Reply
110 webMethods Broker Client Java API Programmers Guide Version8.2

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 {
c = new BrokerClient(broker_host, broker_name, null,
client_group, "Publish Sample #1",null);
} catch (BrokerException ex) {
. . .
}
/* 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) {
. . .
}
webMethods Broker Client Java API Programmers Guide Version8.2 111
6 Using Request-Reply

/* Create the request event */
try {
e = new BrokerEvent(c, "Sample::Request");
} catch (BrokerException ex) {
. . .
}
/* Create tag and set request events 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();
} catch (BrokerException ex) {
. . .
}
try { /* get the events tag */
received_tag = e.getTag();
6 Using Request-Reply
112 webMethods Broker Client Java API Programmers Guide Version8.2

} catch (BrokerException ex) {
. . .
}
/* 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:
public static void main(String args[])
{
SampleCallback1 general_callback =
new SampleCallback1(num_to_receive);
SampleCallback2 specific_callback =
new SampleCallback2(num_to_receive);
. . .
/* Publish the request */
try {
c.publish(e);
} catch (BrokerException ex) {
. . .
}
/* Register general callback */
try {
c.registerCallback(general_callback,null);
} catch (BrokerException ex) {
System.out.println("Error on registering general callback\n"+ex);
return;
}
webMethods Broker Client Java API Programmers Guide Version8.2 113
6 Using Request-Reply

/* 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) {
System.out.println("Error on dispatch\n"+ex);
return;
}
. . .
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.
6 Using Request-Reply
114 webMethods Broker Client Java API Programmers Guide Version8.2

The following example illustrates how to use BrokerClient.publishRequestAndWait:
public static void main(String args[])
{
BrokerClient c;
BrokerEvent e, events[];
int i;
SampleCallback1 general_callback =
new SampleCallback1(num_to_receive);
. . .
/* Register general callback */
try {
c.registerCallback(general_callback,null);
} catch (BrokerException ex) {
. . .
}
/* 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).
webMethods Broker Client Java API Programmers Guide Version8.2 115
6 Using Request-Reply

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) {
. . .
}
if(!permission) {
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) {
. . .
}
if(!permission) {
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.
6 Using Request-Reply
116 webMethods Broker Client Java API Programmers Guide Version8.2

try {
permission = c.canSubscribe("Sample::Request");
} catch (BrokerException ex) {
. . .
}
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);
} catch (BrokerException ex) {
. . .
}
/* Check if it is a request */
try {
event_type_name = e.getEventTypeName();
} catch (BrokerException ex) {
. . .
}
if ((event_type_name != null) &&
webMethods Broker Client Java API Programmers Guide Version8.2 117
6 Using Request-Reply

(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) {
. . .
}
. . .
6 Using Request-Reply
118 webMethods Broker Client Java API Programmers Guide Version8.2

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;
webMethods Broker Client Java API Programmers Guide Version8.2 119
6 Using Request-Reply

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);
} catch (BrokerException ex) {
. . .
}
. . .
6 Using Request-Reply
120 webMethods Broker Client Java API Programmers Guide Version8.2


webMethods Broker Client Java API Programmers Guide Version8.2 121
7 Transaction Semantics
Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122
About Transactional Client Processing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122
Using Broker Transaction Clients . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123
7 Transaction Semantics
122 webMethods Broker Client Java API Programmers Guide Version8.2

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.
webMethods Broker Client Java API Programmers Guide Version8.2 123
7 Transaction Semantics

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.
7 Transaction Semantics
124 webMethods Broker Client Java API Programmers Guide Version8.2

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.
webMethods Broker Client Java API Programmers Guide Version8.2 125
7 Transaction Semantics

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;
}
. . .
7 Transaction Semantics
126 webMethods Broker Client Java API Programmers Guide Version8.2

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).
webMethods Broker Client Java API Programmers Guide Version8.2 127
7 Transaction Semantics

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.
7 Transaction Semantics
128 webMethods Broker Client Java API Programmers Guide Version8.2

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);
}
. . .
webMethods Broker Client Java API Programmers Guide Version8.2 129
7 Transaction Semantics

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);
}
7 Transaction Semantics
130 webMethods Broker Client Java API Programmers Guide Version8.2


webMethods Broker Client Java API Programmers Guide Version8.2 131
8 Publishing and Delivering Events
Publishing Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132
Delivering Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 133
8 Publishing and Delivering Events
132 webMethods Broker Client Java API Programmers Guide Version8.2

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.
webMethods Broker Client Java API Programmers Guide Version8.2 133
8 Publishing and Delivering Events

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 {
c.publish(e);
} catch (BrokerException ex) {
System.out.println("Error on publish\n"+ex);
return;
}
. . .
Publishing Multiple Events
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 {
c.publish(e);
} catch (BrokerException ex) {
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.
8 Publishing and Delivering Events
134 webMethods Broker Client Java API Programmers Guide Version8.2

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) {
System.out.println("Error on getting destination ID\n"+ex);
return;
webMethods Broker Client Java API Programmers Guide Version8.2 135
8 Publishing and Delivering Events

}
/* 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:
A string containing the destination identifier (client identifier of the recipient).
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) {
System.out.println("Error on getting destination ID\n"+ex);
return;
}
/* 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.
8 Publishing and Delivering Events
136 webMethods Broker Client Java API Programmers Guide Version8.2


webMethods Broker Client Java API Programmers Guide Version8.2 137
9 Handling Errors
Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 138
BrokerExceptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 138
Setting the System Diagnostic Level . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 139
9 Handling Errors
138 webMethods Broker Client Java API Programmers Guide Version8.2

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 {
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;
}
. . .
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:
. . .
BrokerClient c;
. . .
/* Create a client */
try {
webMethods Broker Client Java API Programmers Guide Version8.2 139
9 Handling Errors

c = new BrokerClient(broker_host, broker_name, null,
client_group, "Publish Sample #1",null);
} catch (BrokerClientExistsException ex) {
System.out.println("Cant create client, already exists\n");
return;
} catch (BrokerNotRunningException ex) {
System.out.println("Cant 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:
. . .
BrokerClient c;
. . .
/* Create a client */
try {
c = new BrokerClient(broker_host, broker_name, null,
client_group, "Publish Sample #1",null);
} catch (BrokerException ex) {
If(ex instanceof BrokerClientExistsException) {
System.out.println("Cant create client, already exists\n");
return;
} else if(ex instanceof BrokerNotRunningException) {
System.out.println("Cant 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
140 webMethods Broker Client Java API Programmers Guide Version8.2

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.

webMethods Broker Client Java API Programmers Guide Version8.2 141
10 Using BrokerDate Objects
Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 142
Date and Time Representation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 142
BrokerDate Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 142
10 Using BrokerDate Objects
142 webMethods Broker Client Java API Programmers Guide Version8.2

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.
webMethods Broker Client Java API Programmers Guide Version8.2 143
10 Using BrokerDate Objects

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
10 Using BrokerDate Objects
144 webMethods Broker Client Java API Programmers Guide Version8.2


webMethods Broker Client Java API Programmers Guide Version8.2 145
11 Using Sequence Numbers
Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 146
Sequence Numbers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 146
Publisher Sequence Numbers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 146
Receipt Sequence Numbers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 147
11 Using Sequence Numbers
146 webMethods Broker Client Java API Programmers Guide Version8.2

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.
webMethods Broker Client Java API Programmers Guide Version8.2 147
11 Using Sequence Numbers

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.
11 Using Sequence Numbers
148 webMethods Broker Client Java API Programmers Guide Version8.2

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.
webMethods Broker Client Java API Programmers Guide Version8.2 149
11 Using Sequence Numbers

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
11 Using Sequence Numbers
150 webMethods Broker Client Java API Programmers Guide Version8.2

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.

webMethods Broker Client Java API Programmers Guide Version8.2 151
12 Managing Event Types
Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 152
Event Type Definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 152
Event Type Definition Cache . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 155
Infosets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 156
12 Managing Event Types
152 webMethods Broker Client Java API Programmers Guide Version8.2

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.
webMethods Broker Client Java API Programmers Guide Version8.2 153
12 Managing Event Types

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
12 Managing Event Types
154 webMethods Broker Client Java API Programmers Guide Version8.2

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
webMethods Broker Client Java API Programmers Guide Version8.2 155
12 Managing Event Types

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
12 Managing Event Types
156 webMethods Broker Client Java API Programmers Guide Version8.2

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.

webMethods Broker Client Java API Programmers Guide Version8.2 157
13 Using Event Filters
Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 158
Filter Strings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 158
Using Filters with Subscriptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 169
Using BrokerFilters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 169
13 Using Event Filters
158 webMethods Broker Client Java API Programmers Guide Version8.2

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:
webMethods Broker Client Java API Programmers Guide Version8.2 159
13 Using Event Filters

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.
13 Using Event Filters
160 webMethods Broker Client Java API Programmers Guide Version8.2

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
Operator Description
< Less than
<= Less than or equal to
> Greater than
>= Greater than or equal to
= Equal to
== Equal to
!= Not equal to
webMethods Broker Client Java API Programmers Guide Version8.2 161
13 Using Event Filters

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
Operator Description
- Unary minus
* Multiplication
/ Division
% Modulus Division
- Subtraction
+ Addition
Operator Description
~ Bitwise compliment
<< Shift left
>> Shift right
& Logical and
| Logical or
^ Logical exclusive or
Operator Description
+ Concatenation
< Less than
<= Less than or equal to
> Greater than
>= Greater than or equal to
= Equal to
== Equal to
!= Not equal to
13 Using Event Filters
162 webMethods Broker Client Java API Programmers Guide Version8.2

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
webMethods Broker Client Java API Programmers Guide Version8.2 163
13 Using Event Filters

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.
13 Using Event Filters
164 webMethods Broker Client Java API Programmers Guide Version8.2

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=tr
ue
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=tr
ue
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.
s The name of an event field containing a string.
substr The string that is being searched for.
webMethods Broker Client Java API Programmers Guide Version8.2 165
13 Using Event Filters

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.
13 Using Event Filters
166 webMethods Broker Client Java API Programmers Guide Version8.2

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.
s The name of an event field containing a string.
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.
webMethods Broker Client Java API Programmers Guide Version8.2 167
13 Using Event Filters

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.
field The name of an event field to be converted.
field The name of an event field to be converted.
s The name of an event field containing a string.
13 Using Event Filters
168 webMethods Broker Client Java API Programmers Guide Version8.2

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.
Note: This function supports locale sensitivity to the extent possible on your particular
platform.
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.
Note: This function supports locale sensitivity to the extent possible on your particular
platform.
field The name of an event field to be converted.
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.
s The name of an event field containing a string.
webMethods Broker Client Java API Programmers Guide Version8.2 169
13 Using Event Filters

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) {
System.out.println("Error on create subscription\n"+ex);
return;
}
. . .
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;
13 Using Event Filters
170 webMethods Broker Client Java API Programmers Guide Version8.2

}

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.
webMethods Broker Client Java API Programmers Guide Version8.2 171
13 Using Event Filters

Converting Broker Filters to Strings
The BrokerFilter.toString method allows you to obtain a character string containing the
contents of a Broker filter.
13 Using Event Filters
172 webMethods Broker Client Java API Programmers Guide Version8.2


webMethods Broker Client Java API Programmers Guide Version8.2 173
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
14 Load Balancing and Failover for Publish Operations
174 webMethods Broker Client Java API Programmers Guide Version8.2

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.
webMethods Broker Client Java API Programmers Guide Version8.2 175
14 Load Balancing and Failover for Publish Operations

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.
14 Load Balancing and Failover for Publish Operations
176 webMethods Broker Client Java API Programmers Guide Version8.2

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.
webMethods Broker Client Java API Programmers Guide Version8.2 177
14 Load Balancing and Failover for Publish Operations

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 {
14 Load Balancing and Failover for Publish Operations
178 webMethods Broker Client Java API Programmers Guide Version8.2

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;
}
. . .
webMethods Broker Client Java API Programmers Guide Version8.2 179
14 Load Balancing and Failover for Publish Operations

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);
14 Load Balancing and Failover for Publish Operations
180 webMethods Broker Client Java API Programmers Guide Version8.2

} 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;
}
. . .
webMethods Broker Client Java API Programmers Guide Version8.2 181
14 Load Balancing and Failover for Publish Operations

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_DIS
CONNECTED
The Broker as specified by conn_name has left the territory or
down
CONNECT_STATE_CON
NECTED
The Broker as specified by conn_name has joined the territory or
became available
14 Load Balancing and Failover for Publish Operations
182 webMethods Broker Client Java API Programmers Guide Version8.2

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
webMethods Broker Client Java API Programmers Guide Version8.2 183
14 Load Balancing and Failover for Publish Operations

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,
14 Load Balancing and Failover for Publish Operations
184 webMethods Broker Client Java API Programmers Guide Version8.2

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

}
webMethods Broker Client Java API Programmers Guide Version8.2 185
14 Load Balancing and Failover for Publish Operations

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.
14 Load Balancing and Failover for Publish Operations
186 webMethods Broker Client Java API Programmers Guide Version8.2

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.
webMethods Broker Client Java API Programmers Guide Version8.2 187
14 Load Balancing and Failover for Publish Operations

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.
14 Load Balancing and Failover for Publish Operations
188 webMethods Broker Client Java API Programmers Guide Version8.2

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;
}
. . .
Publishing Multiple Events
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];
webMethods Broker Client Java API Programmers Guide Version8.2 189
14 Load Balancing and Failover for Publish Operations

. . .
/* 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:
A string containing the destination identifier (client identifier of the recipient).
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;
}
. . .
14 Load Balancing and Failover for Publish Operations
190 webMethods Broker Client Java API Programmers Guide Version8.2

Delivering Multiple Events
The following example shows the use of the BrokerClusterPublisher.deliver method to deliver a
single event. This method accepts these parameters:
A string containing the destination identifier (client identifier of the recipient).
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.
webMethods Broker Client Java API Programmers Guide Version8.2 191
14 Load Balancing and Failover for Publish Operations

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.
14 Load Balancing and Failover for Publish Operations
192 webMethods Broker Client Java API Programmers Guide Version8.2

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.

webMethods Broker Client Java API Programmers Guide Version8.2 193
15 Working with Basic Authentication
Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 194
Basic Authentication. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 194
Configuring the Broker Java Client for Basic Authentication . . . . . . . . . . . . . . . . . . . . . . . . . . . . 194
15 Working with Basic Authentication
194 webMethods Broker Client Java API Programmers Guide Version8.2

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()
webMethods Broker Client Java API Programmers Guide Version8.2 195
15 Working with Basic Authentication

// 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_PASSWOR
D
System.setProperty("BROKER_
CONNECTION_BASIC_AUTH_PASSW
ORD ", " SoftwareAG123");
15 Working with Basic Authentication
196 webMethods Broker Client Java API Programmers Guide Version8.2


webMethods Broker Client Java API Programmers Guide Version8.2 197
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
198 webMethods Broker Client Java API Programmers Guide Version8.2

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.
webMethods Broker Client Java API Programmers Guide Version8.2 199
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.
Return Type Method Signature and Description
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
200 webMethods Broker Client Java API Programmers Guide Version8.2

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()
Return Type Method Signature and Description
webMethods Broker Client Java API Programmers Guide Version8.2 201
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_CONNECT
ION_SSL_KEYSTORE",
"C:\mykeystore.p12");
Truststore BROKER_CONNECTION_
SSL_TRUSTSTORE
System.setProperty("BROKER_CONNECT
ION_SSL_TRUSTSTORE",
"C:\mytruststore.jks");
Keystore Type BROKER_CONNECTION_
SSL_KEYSTORE_TYPE
System.setProperty("BROKER_CONNECT
ION_SSL_KEYSTORE_TYPE",
"KeystoreType.p12");
Truststore
Type
BROKER_CONNECTION_
SSL_TRUSTSTORE_TYPE
System.setProperty("BROKER_CONNECT
ION_SSL_TRUSTSTORE_TYPE",
"TruststoreType.jks");
Ciphersuites BROKER_CONNECTION_
SSL_CIPHERSUITES
System.setProperty("BROKER_CONNECT
ION_SSL_CIPHERSUITES",
"TLS_RSA_WITH_AES_128_CBC_SHA");
Password BROKER_CONNECTION_
SSL_PASSWORD
System.setProperty("BROKER_CONNECT
ION_SSL_PASSWORD",
"SoftwareAG123");
Provider BROKER_CONNECTION_
SSL_PROVIDER
System.setProperty("BROKER_CONNECT
ION_SSL_PROVIDER", "Entrust");
DN BROKER_CONNECTION_
SSL_DN
System.setProperty("BROKER_CONNECT
ION_SSL_DN", "cn=brokerclient1,
o=webM,st=CA,c=US");
FIPS BROKER_CONNECTION_
SSL_FIPS
System.setProperty("BROKER_CONNECT
ION_SSL_FIPS", "true");
TCP No Delay BROKER_CONNECTION_
TCP_NODELAY
System.setProperty("BROKER_CONNECT
ION_TCP_NODELAY", "true");
16 Working with SSL
202 webMethods Broker Client Java API Programmers Guide Version8.2

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

webMethods Broker Client Java API Programmers Guide Version8.2 203
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.
17 Java API Client Reference
204 webMethods Broker Client Java API Programmers Guide Version8.2

The callback mechanism can only be used with the BrokerClient.mainLoop,
BrokerClient.dispatch, and BrokerClient.threadedCallbacks methods.
handleBrokerEvent
boolean 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.
webMethods Broker Client Java API Programmers Guide Version8.2 205
17 Java API Client Reference

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
17 Java API Client Reference
206 webMethods Broker Client Java API Programmers Guide Version8.2

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
webMethods Broker Client Java API Programmers Guide Version8.2 207
17 Java API Client Reference

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.
17 Java API Client Reference
208 webMethods Broker Client Java API Programmers Guide Version8.2

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.
Possible Exceptions Meaning
webMethods Broker Client Java API Programmers Guide Version8.2 209
17 Java API Client Reference

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.
Possible Exceptions Meaning
BrokerInvalidAcknowledgementExceptio
n
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.
Possible Exceptions Meaning
BrokerInvalidAcknowledgementExceptio
n
The seqn was not a valid event to
acknowledge.
BrokerInvalidClientException The client has been destroyed or
disconnected.
17 Java API Client Reference
210 webMethods Broker Client Java API Programmers Guide Version8.2

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
BrokerOutOfRangeException The seqn was less than zero.
seqn The last event sequence number that is being acknowledged. A
value of 0 will acknowledge all events received that were
previously not acknowledged.
Possible Exceptions Meaning
BrokerInvalidAcknowledgementExceptio
n
The seqn was not a valid event to
acknowledge.
BrokerInvalidClientException The client has been destroyed or
disconnected.
BrokerOutOfRangeException The seqn was less than zero.
Possible Exceptions Meaning
webMethods Broker Client Java API Programmers Guide Version8.2 211
17 Java API Client Reference

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.
Possible Exceptions Meaning
BrokerInvalidClientException The client has been destroyed or
disconnected.
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.
17 Java API Client Reference
212 webMethods Broker Client Java API Programmers Guide Version8.2

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
Possible Exceptions Meaning
BrokerInvalidClientException The client has been destroyed or
disconnected.
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.
Possible Exceptions Meaning
BrokerInvalidClientException The client has been destroyed or
disconnected.
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.
webMethods Broker Client Java API Programmers Guide Version8.2 213
17 Java API Client Reference

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.
Possible Exceptions Meaning
BrokerInvalidClientException The client has been destroyed or
disconnected.
BrokerNullParameterException The event_type_name parameter is null.
BrokerUnknownEventTypeException The event type does not exist on the
Broker.
sub_id The subscription identifier associated
with the callback method to be cancelled.
Possible Exceptions Meaning
BrokerInvalidClientException The client has been destroyed or
disconnected.
tag The tag associated with the callback
method to be cancelled.
17 Java API Client Reference
214 webMethods Broker Client Java API Programmers Guide Version8.2

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
Possible Exceptions Meaning
BrokerInvalidClientException The client has been destroyed or
disconnected.
Possible Exceptions Meaning
BrokerInvalidClientException The client has been destroyed or
disconnected.
Possible Exceptions Meaning
BrokerInvalidClientException The client has been destroyed or
disconnected.
event_type_name The event type name associated with the subscription. See
Parameter Naming Rules on page 419 for restrictions on
event type names.
webMethods Broker Client Java API Programmers Guide Version8.2 215
17 Java API Client Reference

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.
Possible Exceptions Meaning
BrokerInvalidClientException The client has been destroyed or
disconnected.
BrokerInvalidSubscriptionException There was no existing subscription that
matched event_type_name and filter.
BrokerNullParameterException The event_type_name parameter is null.
sub The subscription to be cancelled, consisting of a subscription identifier, an
event type name, and a filter.
Possible Exceptions Meaning
BrokerInvalidClientException The client has been destroyed or
disconnected.
BrokerInvalidSubscriptionException There was no existing subscription that
matched sub.
BrokerNullParameterException The sub or sub.event_type_name is null.
17 Java API Client Reference
216 webMethods Broker Client Java API Programmers Guide Version8.2

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.
Possible Exceptions Meaning
BrokerInvalidClientException The client has been destroyed or
disconnected.
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.
webMethods Broker Client Java API Programmers Guide Version8.2 217
17 Java API Client Reference

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.
Possible Exceptions Meaning
BrokerInterruptedException The BrokerClient.interruptCheckForEvents
method was used to stop the call.
BrokerInvalidClientException The client has been destroyed or
disconnected.
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.
Possible Exceptions Meaning
BrokerInvalidClientException The client has been destroyed or
disconnected.
17 Java API Client Reference
218 webMethods Broker Client Java API Programmers Guide Version8.2

Returns a BrokerClientQueueBrowser object if successful, otherwise throws a
BrokerException. See the webMethods Broker Administration Java API Programmers 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.
Possible Exceptions Meaning
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.
Possible Exceptions Meaning
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.
webMethods Broker Client Java API Programmers Guide Version8.2 219
17 Java API Client Reference

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
BrokerUnknownEventTypeException The event type does not exist on the
Broker.
dest_id The client identifier of the Broker client that is to receive the events.
events The array of BrokerEvent objects to be delivered.
Possible Exceptions Meaning
BrokerInvalidClientException This BrokerClient has been destroyed or
disconnected.
BrokerInvalidClientIdException This dest_id contains invalid characters.
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.
Possible Exceptions Meaning
17 Java API Client Reference
220 webMethods Broker Client Java API Programmers Guide Version8.2

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.
Possible Exceptions Meaning
BrokerInvalidClientException This BrokerClient has been destroyed or
disconnected.
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.
webMethods Broker Client Java API Programmers Guide Version8.2 221
17 Java API Client Reference

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.
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.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
Possible Exceptions Meaning
BrokerInvalidClientException This BrokerClient has been destroyed or
disconnected.
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.
17 Java API Client Reference
222 webMethods Broker Client Java API Programmers Guide Version8.2

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.
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.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.
Possible Exceptions Meaning
BrokerInvalidClientException This BrokerClient has been destroyed or
disconnected.
BrokerInvalidEventException The event does not match its type
definition.
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
webMethods Broker Client Java API Programmers Guide Version8.2 223
17 Java API Client Reference

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.
Note: No exception will be thrown if the recipient, represented by the pubId field in
request_event, no longer exists.
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.
Possible Exceptions Meaning
BrokerInvalidClientException This BrokerClient has been destroyed or
disconnected.
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.
17 Java API Client Reference
224 webMethods Broker Client Java API Programmers Guide Version8.2

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.
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.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.
Possible Exceptions Meaning
BrokerInvalidClientException This BrokerClient has been destroyed or
disconnected.
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.
webMethods Broker Client Java API Programmers Guide Version8.2 225
17 Java API Client Reference

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.
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.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.
Possible Exceptions Meaning
BrokerInvalidClientException This BrokerClient has been destroyed or
disconnected.
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.
17 Java API Client Reference
226 webMethods Broker Client Java API Programmers Guide Version8.2

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
Possible Exceptions Meaning
BrokerBadStateException This method was called from a callback
method.
BrokerInvalidClientException This BrokerClient has been destroyed or
disconnected.
BrokerInvalidClientIdException The dest_id contains invalid characters.
BrokerInvalidEventException The event does not match its event type.
BrokerNoPermissionException The client does not have permission to
publish the 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
events The array of BrokerEvent objects to be delivered.
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
webMethods Broker Client Java API Programmers Guide Version8.2 227
17 Java API Client Reference

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.
Possible Exceptions Meaning
BrokerInvalidAcknowledgementExceptio
n
The parameter ack_seqn contained an
invalid sequence number. The events
were not sent to the Broker.
BrokerInvalidClientException This BrokerClient has been destroyed or
disconnected.
BrokerInvalidClientIdException This dest_id contains invalid characters.
BrokerInvalidEventException One or more of the events does not match
its type definition.
17 Java API Client Reference
228 webMethods Broker Client Java API Programmers Guide Version8.2

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.
BrokerUnknownEventTypeException One or more of the event types does not
exist on the Broker.
Possible Exceptions Meaning
BrokerInvalidClientException The client has been destroyed or
disconnected.
Possible Exceptions Meaning
webMethods Broker Client Java API Programmers Guide Version8.2 229
17 Java API Client Reference

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
Possible Exceptions Meaning
BrokerInvalidClientException The client has been destroyed or
disconnected.
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.
Possible Exceptions Meaning
BrokerBadStateException This method was called from a callback
method.
BrokerInterruptedException The interruptDispatch method was invoked.
BrokerInvalidClientException The client has been destroyed or
disconnected.
17 Java API Client Reference
230 webMethods Broker Client Java API Programmers Guide Version8.2

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.
event_type_name The event type name associated with the 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 no filter was specified in the subscription.
Possible Exceptions Meaning
BrokerInvalidClientException The client has been destroyed or
disconnected.
Possible Exceptions Meaning
webMethods Broker Client Java API Programmers Guide Version8.2 231
17 Java API Client Reference

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
Possible Exceptions Meaning
BrokerInvalidClientException The client has been destroyed or
disconnected.
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.
Possible Exceptions Meaning
BrokerInvalidClientException The client has been destroyed or
disconnected.
BrokerNoPermissionException The client does not have permission to
publish Adapter::endTransaction.
BrokerOutOfRangeException The mode parameter contains an invalid
value.
17 Java API Client Reference
232 webMethods Broker Client Java API Programmers Guide Version8.2

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
Possible Exceptions Meaning
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.
BrokerInvalidClientException The client has been destroyed or
disconnected.
BrokerNoPermissionException The client does not have an owner so it
cannot have an access label.
webMethods Broker Client Java API Programmers Guide Version8.2 233
17 Java API Client Reference

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
Possible Exceptions Meaning
BrokerInvalidClientException The client has been destroyed or
disconnected.
Possible Exceptions Meaning
BrokerBadStateException The client is not using SSL.
BrokerInvalidClientException The client has been destroyed or
disconnected.
17 Java API Client Reference
234 webMethods Broker Client Java API Programmers Guide Version8.2

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.
Possible Exceptions Meaning
BrokerInvalidClientException The client has been destroyed or
disconnected.
Possible Exceptions Meaning
BrokerInvalidClientException The client has been destroyed or
disconnected.
webMethods Broker Client Java API Programmers Guide Version8.2 235
17 Java API Client Reference

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.
See also: BrokerClient.BrokerClient and BrokerClient.reconnect
getClientId
String getClientId()
Returns the client identifier for this BrokerClient.
See also: BrokerClient.BrokerClient and BrokerClient.reconnect
getClientInfoset
BrokerEvent getClientInfoset()
throws BrokerException
Returns the infoset for this client, which is returned as a BrokerEvent for convenience.
Possible Exceptions Meaning
BrokerInvalidClientException The client has been destroyed or
disconnected.
Possible Exceptions Meaning
BrokerInvalidClientException The client has been destroyed or
disconnected.
Possible Exceptions Meaning
BrokerInvalidClientException The client has been destroyed or
disconnected.
17 Java API Client Reference
236 webMethods Broker Client Java API Programmers Guide Version8.2

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
Possible Exceptions Meaning
BrokerBadStateException The client is not using SSL.
BrokerInvalidClientException The client has been destroyed or
disconnected.
webMethods Broker Client Java API Programmers Guide Version8.2 237
17 Java API Client Reference

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.
Possible Exceptions Meaning
BrokerInterruptedException The interruptGetEvents method was invoked.
BrokerInvalidClientException The client has been destroyed or
disconnected.
BrokerOutOfRangeException The msecs is less than -1.
BrokerTimeoutException The wait time expired.
17 Java API Client Reference
238 webMethods Broker Client Java API Programmers Guide Version8.2

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.
Possible Exceptions Meaning
BrokerInterruptedException The interruptGetEvents method was invoked.
webMethods Broker Client Java API Programmers Guide Version8.2 239
17 Java API Client Reference

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.
BrokerInvalidClientException The client has been destroyed or
disconnected.
BrokerOutOfRangeException The msecs is less than -1 or max_events is
less than zero.
BrokerTimeoutException The wait time expired.
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.
Possible Exceptions Meaning
17 Java API Client Reference
240 webMethods Broker Client Java API Programmers Guide Version8.2

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
Possible Exceptions Meaning
BrokerInterruptedException The interruptGetEvents method was invoked.
BrokerInvalidClientException The client has been destroyed or
disconnected.
BrokerOutOfRangeException The msecs is less than -1, max_events is less
than zero, or seqn is less than -1.
BrokerTimeoutException The wait time expired.
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.
Possible Exceptions Meaning
BrokerInvalidClientException The client has been destroyed or
disconnected.
BrokerNoPermissionException The client does not have permission to
publish or subscribe to the event type.
BrokerNullParameterException The event_type_name parameter is null.
BrokerUnknownEventTypeException The event type does not exist on the
Broker.
webMethods Broker Client Java API Programmers Guide Version8.2 241
17 Java API Client Reference

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.
Possible Exceptions Meaning
BrokerInvalidClientException The client has been destroyed or
disconnected.
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.
17 Java API Client Reference
242 webMethods Broker Client Java API Programmers Guide Version8.2

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
Possible Exceptions Meaning
BrokerInvalidClientException The client has been destroyed or
disconnected.
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.
BrokerUnknownEventTypeException The event type does not exist on the
Broker.
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.
Possible Exceptions Meaning
BrokerInvalidClientException The client has been destroyed or
disconnected.
BrokerNoPermissionException The client does not have permission to
publish or subscribe to the event type.
BrokerNullParameterException The event_type_name parameter is null.
BrokerUnknownEventTypeException The event type does not exist on the
Broker.
webMethods Broker Client Java API Programmers Guide Version8.2 243
17 Java API Client Reference

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.
Possible Exceptions Meaning
BrokerInvalidClientException The client has been destroyed or
disconnected.
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.
17 Java API Client Reference
244 webMethods Broker Client Java API Programmers Guide Version8.2

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
Possible Exceptions Meaning
BrokerInvalidClientException The client has been destroyed or
disconnected.
scope_name The event type scope whose names are to
be returned.
Possible Exceptions Meaning
BrokerInvalidClientException The client has been destroyed or
disconnected.
BrokerNullParameterException The scope_name parameter is null.
BrokerUnknownEventTypeException The scope does not exist on the Broker.
Possible Exceptions Meaning
BrokerInvalidClientException The client has been destroyed or
disconnected.
webMethods Broker Client Java API Programmers Guide Version8.2 245
17 Java API Client Reference

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.
Possible Exceptions Meaning
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.
Possible Exceptions Meaning
BrokerInvalidClientException The client has been destroyed or
disconnected.
17 Java API Client Reference
246 webMethods Broker Client Java API Programmers Guide Version8.2

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.
Possible Exceptions Meaning
BrokerInvalidClientException The client has been destroyed or
disconnected.
Possible Exceptions Meaning
BrokerInvalidClientException The client has been destroyed or
disconnected.
webMethods Broker Client Java API Programmers Guide Version8.2 247
17 Java API Client Reference

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.
Possible Exceptions Meaning
BrokerInvalidClientException The client has been destroyed or
disconnected.
Possible Exceptions Meaning
BrokerInvalidClientException The client has been destroyed or
disconnected.
seqn The receipt sequence number of the event
whose redelivery counter is to be
incremented.
17 Java API Client Reference
248 webMethods Broker Client Java API Programmers Guide Version8.2

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
Possible Exceptions Meaning
BrokerInvalidClientException The client has been destroyed or
disconnected.
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.
Possible Exceptions Meaning
BrokerInvalidClientException The client has been destroyed or
disconnected.
Possible Exceptions Meaning
BrokerInvalidClientException The client has been destroyed or
disconnected.
webMethods Broker Client Java API Programmers Guide Version8.2 249
17 Java API Client Reference

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.
Possible Exceptions Meaning
BrokerInvalidClientException The client has been destroyed or
disconnected.
Possible Exceptions Meaning
BrokerInvalidClientException The client has been destroyed or
disconnected.
Possible Exceptions Meaning
BrokerInvalidClientException The client has been destroyed or
disconnected.
17 Java API Client Reference
250 webMethods Broker Client Java API Programmers Guide Version8.2

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
Possible Exceptions Meaning
BrokerBadStateException This method was called from a callback
method.
webMethods Broker Client Java API Programmers Guide Version8.2 251
17 Java API Client Reference

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.
Possible Exceptions Meaning
BrokerInvalidClientException The client has been destroyed or
disconnected.
Possible Exceptions Meaning
BrokerInvalidClientException The client has been destroyed or
disconnected.
seqn The event sequence number that is being
negative acknowledged. The value must
be greater than 0.
17 Java API Client Reference
252 webMethods Broker Client Java API Programmers Guide Version8.2

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
Possible Exceptions Meaning
BrokerInvalidClientException The client has been destroyed or
disconnected.
BrokerOutOfRangeException seqn is a negative number or 0.
BrokerInvalidOperationException Cannot increment the counter because the
client is configured to use automatic
incrementing.
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.
Possible Exceptions Meaning
BrokerInvalidClientException The client has been destroyed or
disconnected.
BrokerOutOfRangeException seqn is a negative number or 0.
BrokerInvalidOperationException Cannot increment the counter because the
client is configured to use automatic
incrementing.
BrokerInvalidSequenceNumberException seqn does not correspond to a received
array of events.
webMethods Broker Client Java API Programmers Guide Version8.2 253
17 Java API Client Reference

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.
app_name The name of the application that will
contain the new Broker client.
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.
17 Java API Client Reference
254 webMethods Broker Client Java API Programmers Guide Version8.2

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
Possible Exceptions Meaning
BrokerClientContentionException Another Broker client is already using the
specified client_id. For clients with shared
state, the maximum number of reconnects
has been exceeded.
BrokerCommFailureException A problem occurred establishing the
connection.
BrokerHostNotFoundException The specified broker_host does not exist.
BrokerInvalidClientIdException The client_id 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_id, 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 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.
webMethods Broker Client Java API Programmers Guide Version8.2 255
17 Java API Client Reference

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.
Possible Exceptions Meaning
BrokerInvalidClientException The client has been destroyed or
disconnected.
BrokerInvalidSubscriptionException The filter string contains a parse error.
BrokerNoPermissionException The client does not have permission to
subscribe to the event type.
BrokerNullParameterException The event_type_name parameter is null.
BrokerUnknownEventTypeException The event type does not exist on the
Broker.
17 Java API Client Reference
256 webMethods Broker Client Java API Programmers Guide Version8.2

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.
event_type_name The event type name associated with the
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.
Possible Exceptions Meaning
BrokerInvalidClientException The client has been destroyed or
disconnected.
BrokerInvalidSubscriptionException The filter string contains a parse error.
BrokerNoPermissionException The client does not have permission to
subscribe to the event type.
BrokerNullParameterException The event_type_name parameter is null.
BrokerOutOfRangeException The sub_id is less that zero.
BrokerUnknownEventTypeException The event type does not exist on the
Broker.
webMethods Broker Client Java API Programmers Guide Version8.2 257
17 Java API Client Reference

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.
Possible Exceptions Meaning
BrokerInvalidClientException The client has been destroyed or
disconnected.
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.
BrokerUnknownEventTypeException The event type does not exist on the
Broker.
17 Java API Client Reference
258 webMethods Broker Client Java API Programmers Guide Version8.2

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.
Possible Exceptions Meaning
BrokerInvalidClientException The client has been destroyed or
disconnected.
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.
BrokerUnknownEventTypeException One or more of the event types does not
exist on the Broker.
polls The array of BrokerClientPoll objects that
belong to the Broker clients for which this
method will perform polling.
webMethods Broker Client Java API Programmers Guide Version8.2 259
17 Java API Client Reference

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.
17 Java API Client Reference
260 webMethods Broker Client Java API Programmers Guide Version8.2

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.
Possible Exceptions Meaning
BrokerInvalidClientException The client has been destroyed or
disconnected.
event The event to be published.
Possible Exceptions Meaning
BrokerInvalidClientException The client has been destroyed or
disconnected.
BrokerInvalidEventException The event does not match its type
definition.
BrokerNoPermissionException The client does not have permission to
publish the event type.
BrokerNullParameterException The event parameter is null.
webMethods Broker Client Java API Programmers Guide Version8.2 261
17 Java API Client Reference

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
BrokerUnknownEventTypeException The event type does not exist on the
Broker.
events An array of events to be published.
Possible Exceptions Meaning
BrokerInvalidClientException The client has been destroyed or
disconnected.
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.
BrokerUnknownEventTypeException One or more of the event types does not
exist on the Broker.
event The request event to be published.
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.
Possible Exceptions Meaning
17 Java API Client Reference
262 webMethods Broker Client Java API Programmers Guide Version8.2

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
Possible Exceptions Meaning
BrokerBadStateException This method was called from a callback
method.
BrokerInvalidClientException The client has been destroyed or
disconnected.
BrokerInvalidEventException The event does not match its type
definition.
BrokerNoPermissionException The client does not have permission to
publish the event type.
BrokerNullParameterException The event parameteris null.
BrokerUnknownEventTypeException The event type does not exist on the
Broker.
events An array of events to be published.
webMethods Broker Client Java API Programmers Guide Version8.2 263
17 Java API Client Reference

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.
17 Java API Client Reference
264 webMethods Broker Client Java API Programmers Guide Version8.2

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
Possible Exceptions Meaning
BrokerInvalidAcknowledgementExceptio
n
The parameter ack_seqn contained an
invalid sequence number. The events
were not sent to the Broker.
BrokerInvalidClientException The client has been destroyed or
disconnected.
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.
BrokerUnknownEventTypeException One or more of the event types does not
exist on the Broker.
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
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.
webMethods Broker Client Java API Programmers Guide Version8.2 265
17 Java API Client Reference

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.
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.
Possible Exceptions Meaning
BrokerClientContentionException Another Broker client is already using the
specified client_id. For clients with shared
state, the maximum number of reconnects
has been exceeded.
BrokerCommFailureException A problem occurred establishing the
connection.
BrokerHostNotFoundException The specified broker_host does not exist.
BrokerNoPermissionException Permission to join the client_group was
denied.
BrokerNotRunningException A Broker could not be found on the
broker_host.
BrokerNullParameterException The broker_host or client_id 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 there is no
default Broker.
BrokerUnknownClientIdException The specified client_id does not exist on
the Broker.
17 Java API Client Reference
266 webMethods Broker Client Java API Programmers Guide Version8.2

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.
Possible Exceptions Meaning
BrokerInvalidClientException The client has been destroyed or
disconnected.
BrokerNullParameterException The obj parameter is null.
sub_id The subscription identifier to match for
this callback.
webMethods Broker Client Java API Programmers Guide Version8.2 267
17 Java API Client Reference

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.
client_data Any data which you want to pass to the
callback method when it is invoked.
Possible Exceptions Meaning
BrokerBadStateException No general callback was registered prior
to calling this method.
BrokerInvalidClientException The client has been destroyed or
disconnected.
BrokerNullParameterException The obj parameter is null.
BrokerOutOfRangeException The sub_id parameter is less than zero.
tag The subscription identifier to match for
this callback.
17 Java API Client Reference
268 webMethods Broker Client Java API Programmers Guide Version8.2

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.
client_data Any data which you want to pass to the
callback method when it is invoked.
Possible Exceptions Meaning
BrokerBadStateException No general callback was registered prior
to calling this method.
BrokerInvalidClientException The client has been destroyed or
disconnected.
BrokerNullParameterException The obj parameter is null.
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.
webMethods Broker Client Java API Programmers Guide Version8.2 269
17 Java API Client Reference

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.
Possible Exceptions Meaning
BrokerInvalidClientException The client has been destroyed or
disconnected.
seqn A list of unacknowledged documents
from the client queue that matches the
given receipt of sequence numbers, seqn.
Possible Exceptions Meaning
BrokerInterruptedException The interruptGetEvents is used to stop the
call.
BrokerInvalidClientException The client has been destroyed or
disconnected.
BrokerOutOfRangeException A duplicate/invalid seqn#.
17 Java API Client Reference
270 webMethods Broker Client Java API Programmers Guide Version8.2

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.
Possible Exceptions Meaning
BrokerInvalidClientException The client has been destroyed or
disconnected.
infoset The infoset to set for this client.
Possible Exceptions Meaning
BrokerInvalidClientException The client has been destroyed or
disconnected.
BrokerNullParameterException The infoset parameter is null.
msecs The number of milliseconds to wait for an
event to process before timing out.
webMethods Broker Client Java API Programmers Guide Version8.2 271
17 Java API Client Reference

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.
Possible Exceptions Meaning
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.
17 Java API Client Reference
272 webMethods Broker Client Java API Programmers Guide Version8.2

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
Possible Exceptions Meaning
BrokerInvalidClientException The client has been destroyed or
disconnected.
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.
webMethods Broker Client Java API Programmers Guide Version8.2 273
17 Java API Client Reference

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:
17 Java API Client Reference
274 webMethods Broker Client Java API Programmers Guide Version8.2

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.
webMethods Broker Client Java API Programmers Guide Version8.2 275
17 Java API Client Reference

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
17 Java API Client Reference
276 webMethods Broker Client Java API Programmers Guide Version8.2

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
Possible Exception Meaning
BrokerInvalidPollOperationException Value specified in operations is invalid.
operations The operation whose state you want to
check. Must be set to:
BrokerClientPoll.GET_EVENTS
Possible Exception Meaning
BrokerInvalidPollOperationException Value specified in operations is invalid.
webMethods Broker Client Java API Programmers Guide Version8.2 277
17 Java API Client Reference

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
BrokerClusterPublisher
BrokerClusterPublisherextends 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_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.
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.
17 Java API Client Reference
278 webMethods Broker Client Java API Programmers Guide Version8.2

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()
app_name The name of the application that will
contain the new Broker client.
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.
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.
Possible Exceptions Meaning
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.
webMethods Broker Client Java API Programmers Guide Version8.2 279
17 Java API Client Reference

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.
In addition to the listed exceptions, any communications exception can be thrown.
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.
Possible Exceptions Meaning
BrokerInvalidClientException The client has been destroyed or
disconnected.
BrokerNullParameterException broker_host, client_group, or app_name are
null.
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.
17 Java API Client Reference
280 webMethods Broker Client Java API Programmers Guide Version8.2

Note: An exception will not be thrown if the recipient, represented by dest_id, no longer
exists.
In addition to the listed exceptions, any communications exception can be thrown.
deliver
void deliver(
java.lang.String dest_id,
BrokerEvent[] event)
throws BrokerException
Note: An exception will not be thrown if the recipient, represented by dest_id, no longer
exists.
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.
Possible Exceptions Meaning
BrokerInvalidClientException The client has been destroyed or
disconnected.
BrokerNullParameterException broker_host, client_group, or app_name are
null.
BrokerInvalidEventException The event does not match its type
definition.
BrokerNoPermissionException The client does not have permission to
publish the event type.
BrokerUnknownEventTypeException The event type for the event 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 events
events The array of BrokerEvent objects to be
delivered.
Possible Exceptions Meaning
BrokerInvalidClientException The client has been destroyed or
disconnected.
BrokerNullParameterException broker_host, client_group, or app_name are
null.
webMethods Broker Client Java API Programmers Guide Version8.2 281
17 Java API Client Reference

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.
In addition to the listed exceptions, any communications exception can be thrown.
BrokerInvalidEventException The event does not match its type
definition.
BrokerNoPermissionException The client does not have permission to
publish the event type.
BrokerUnknownEventTypeException The event type for the event does not exist
on the broker.
BrokerClusterPublisherIdException No Broker is available on the cluster pool.
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.
retry
Possible Exceptions Meaning
BrokerBadStateException This is called from within a callback
function
Possible Exceptions Meaning
17 Java API Client Reference
282 webMethods Broker Client Java API Programmers Guide Version8.2

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.
BrokerInvalidClientException The client has been destroyed or
disconnected.
BrokerInvalidClientIdException the destination ID includes invalid
characters
BrokerNullParameterException broker_host, client_group, or app_name are
null.
BrokerInvalidEventException The event does not match its type
definition.
BrokerNoPermissionException The client does not have permission to
publish the event type.
BrokerUnknownEventTypeException The event type for the event does not exist
on the broker.
BrokerClusterPublisherIdException No Broker is available on the cluster pool.
Possible Exceptions Meaning
BrokerInvalidClientException The client has been destroyed or
disconnected.
Possible Exception Meaning
BrokerInvalidClientException The client has been destroyed or
disconnected.
Possible Exceptions Meaning
webMethods Broker Client Java API Programmers Guide Version8.2 283
17 Java API Client Reference

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
In addition to the listed exceptions, any communications exception can be thrown.
brokerName Name of the Broker to exclude from
cluster operations.
Possible Exceptions Meaning
BrokerInvalidClientException The client has been destroyed or
disconnected.
BrokerClusterPublisherException The specified broker is not part of the
cluster publisher operation or the last
single broker client connection found on
the client pool.
Possible Exceptions Meaning
BrokerInvalidClientException The client has been destroyed or
disconnected.
BrokerClusterPublisherIdException No Broker is available on the cluster pool.
17 Java API Client Reference
284 webMethods Broker Client Java API Programmers Guide Version8.2

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.
webMethods Broker Client Java API Programmers Guide Version8.2 285
17 Java API Client Reference

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.
17 Java API Client Reference
286 webMethods Broker Client Java API Programmers Guide Version8.2

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.
Possible Exceptions Meaning
BrokerInvalidClientException The client has been destroyed or
disconnected.
BrokerClusterPublisherIdException No Broker is available on the cluster pool.
brokerName Name of the Broker to include from
cluster operations.
event The event to be published
webMethods Broker Client Java API Programmers Guide Version8.2 287
17 Java API Client Reference

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.
Possible Exceptions Meaning
BrokerInvalidClientException The client has been destroyed or
disconnected.
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.
BrokerUnknownClusterPublisherExcepti
on
No Broker is available on the cluster pool.
events An array of events to be published.
Possible Exceptions Meaning
BrokerInvalidClientException The client has been destroyed or
disconnected.
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.
BrokerUnknownClusterPublisherExcepti
on
No Broker is available on the cluster pool.
17 Java API Client Reference
288 webMethods Broker Client Java API Programmers Guide Version8.2

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
event The request event to be published.
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.
Possible Exceptions Meaning
BrokerBadStateException Called from within a callback function.
BrokerInvalidClientException The client has been destroyed or
disconnected.
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.
BrokerUnknownClusterPublisherExcepti
on
No Broker is available on the cluster pool.
webMethods Broker Client Java API Programmers Guide Version8.2 289
17 Java API Client Reference

Attempts to create BrokerClusterPublisher. If the creation fails because the client already
exists, then it reconnects to the client instead.
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 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.
app_name The name of the application that will
contain the new Broker client.
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.
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.
Possible Exceptions Meaning
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.
BrokerCommFailureException If problems occur establishing the
connection.
BrokerHostNotFoundException If the specified host does not exist.
17 Java API Client Reference
290 webMethods Broker Client Java API Programmers Guide Version8.2

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.
BrokerInvalidClientIdException The ID 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.
BrokerUnknownClientIdException The specified client ID does not exist on
the broker.
event The request event to be published.
Possible Exceptions Meaning
BrokerInvalidClientException The client has been destroyed or
disconnected.
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.
Possible Exceptions Meaning
webMethods Broker Client Java API Programmers Guide Version8.2 291
17 Java API Client Reference

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
BrokerUnknownClusterPublisherExcepti
on
No Broker is available on the cluster pool.
events The request events to be published.
Possible Exceptions Meaning
BrokerInvalidClientException The client has been destroyed or
disconnected.
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.
BrokerUnknownClusterPublisherExcepti
on
No Broker is available on the cluster pool.
event The request event to be published.
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.
Possible Exceptions Meaning
17 Java API Client Reference
292 webMethods Broker Client Java API Programmers Guide Version8.2

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
Possible Exceptions Meaning
BrokerBadStateException Called from within a callback function.
BrokerInvalidClientException The client has been destroyed or
disconnected.
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.
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
webMethods Broker Client Java API Programmers Guide Version8.2 293
17 Java API Client Reference

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.
.
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 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.
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.
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.
Possible Exceptions Meaning
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.
BrokerCommFailureException If problems occur establishing the
connection.
BrokerHostNotFoundException If the specified host does not exist.
BrokerNoPermissionException Permission to join the specified client
group is denied.
17 Java API Client Reference
294 webMethods Broker Client Java API Programmers Guide Version8.2

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)
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.
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.
Possible Exceptions Meaning
BrokerInvalidClientException The client has been destroyed or
disconnected.
BrokerNullParameterException obj is null.
Possible Exceptions Meaning
webMethods Broker Client Java API Programmers Guide Version8.2 295
17 Java API Client Reference

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.
17 Java API Client Reference
296 webMethods Broker Client Java API Programmers Guide Version8.2

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.
webMethods Broker Client Java API Programmers Guide Version8.2 297
17 Java API Client Reference

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.
17 Java API Client Reference
298 webMethods Broker Client Java API Programmers Guide Version8.2

Constructor
BrokerConnectionDescriptor
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(
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
webMethods Broker Client Java API Programmers Guide Version8.2 299
17 Java API Client Reference

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
17 Java API Client Reference
300 webMethods Broker Client Java API Programmers Guide Version8.2

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:
webMethods Broker Client Java API Programmers Guide Version8.2 301
17 Java API Client Reference

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.
For more information about the keep-alive feature, see Using Client Keep-Alive on
page 52.
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.
For more information about the keep-alive feature, see Using Client Keep-Alive on
page 52.
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()
17 Java API Client Reference
302 webMethods Broker Client Java API Programmers Guide Version8.2

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.
Possible Exceptions Meaning
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.
webMethods Broker Client Java API Programmers Guide Version8.2 303
17 Java API Client Reference

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.
password The keystore file's password.
Possible Exceptions Meaning
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.
BrokerSecurityException SSL support is not available.
Possible Exceptions Meaning
17 Java API Client Reference
304 webMethods Broker Client Java API Programmers Guide Version8.2

Note: This method is included for backward compatibility support only, for SSL
certificates saved in the Spyrus format.
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).
Note: This method is included for backward compatibility support only, for SSL
certificates saved in the Spyrus format.
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.
Note: This method is included for backward compatibility support only, for SSL
certificates saved in the Spyrus format.
webMethods Broker Client Java API Programmers Guide Version8.2 305
17 Java API Client Reference

See also: BrokerConnectionDescriptor.getSSLCertificateFile,
BrokerConnectionDescriptor.setSSLCertificate, and BrokerClient.getClientSSLEncryptionLevel
getSSLKeystore
String getSSLKeystore()
Returns the name of the client keystore file.
getSSLKeystoreType
KeystoreType getSSLKeystoreType()
Returns an enumeration for the file type of the keystore file. Currently, the only value is
PKCS12.
getSSLKeystoreType
KeystoreType 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.
17 Java API Client Reference
306 webMethods Broker Client Java API Programmers Guide Version8.2

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.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.
Possible Exceptions Meaning
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.
BrokerSecurityException SSL support is not available.
hint The access label hint to be set for this
descriptor. This can be set to null.
webMethods Broker Client Java API Programmers Guide Version8.2 307
17 Java API Client Reference

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.
For more information about counting redeliveries, see Detecting Redelivered Events on
page 95.
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.
17 Java API Client Reference
308 webMethods Broker Client Java API Programmers Guide Version8.2

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.
webMethods Broker Client Java API Programmers Guide Version8.2 309
17 Java API Client Reference

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_VAL
UE*
Integer.MAX_VAL
UE*
MaxResponseTime 60 60 Integer.MAX_VAL
UE*
RetryCount 3 3 1*
17 Java API Client Reference
310 webMethods Broker Client Java API Programmers Guide Version8.2

* Required field for the specified keep-alive mode
For more information about the keep-alive feature, see Using Client Keep-Alive on
page 52.
See also: BrokerConnectionDescriptor.getKeepAlivePeriod,
BrokerConnectionDescriptor.getKeepAliveResponseTime, and
BrokerConnectionDescriptor.getKeepAliveRetryCount
setRedeliveryCountEnabled
void setRedeliveryCountEnabled(boolean on)
Enables or disables redelivery counting for this connection descriptor.
For more information about counting redeliveries, see Detecting Redelivered Events on
page 95.
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
webMethods Broker Client Java API Programmers Guide Version8.2 311
17 Java API Client Reference

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.
Possible Exceptions Meaning
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.
password The keystore file's password.
17 Java API Client Reference
312 webMethods Broker Client Java API Programmers Guide Version8.2

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.
Possible Exceptions Meaning
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.
BrokerSecurityException SSL support is not available.
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.
webMethods Broker Client Java API Programmers Guide Version8.2 313
17 Java API Client Reference

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.
17 Java API Client Reference
314 webMethods Broker Client Java API Programmers Guide Version8.2

BrokerCPConnectionCallback
public 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_*.
BrokerCPSelectionCallback
public 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.
client_data Any data that your callback method
needs to perform its processing. This data
is defined when you register your
BrokerConnectionCallback object.
webMethods Broker Client Java API Programmers Guide Version8.2 315
17 Java API Client Reference

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.
client_data Any data that your callback method
needs to perform its processing. This data
is defined when you register your
BrokerConnectionCallback object.
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.
client_data Any data that your callback method
needs to perform its processing. This data
is defined when you register your
BrokerConnectionCallback object.
17 Java API Client Reference
316 webMethods Broker Client Java API Programmers Guide Version8.2

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.
webMethods Broker Client Java API Programmers Guide Version8.2 317
17 Java API Client Reference

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.
17 Java API Client Reference
318 webMethods Broker Client Java API Programmers Guide Version8.2

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.
Possible Exceptions Meaning
java.text.ParseException A parsing error was encountered in the
date_string.
date_string The string containing the date to set in the
newly created BrokerDate object.
locale The locale to be used for the date string.
webMethods Broker Client Java API Programmers Guide Version8.2 319
17 Java API Client Reference

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
Possible Exceptions Meaning
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.
17 Java API Client Reference
320 webMethods Broker Client Java API Programmers Guide Version8.2

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"
Possible Exceptions Meaning
BrokerOutOfRangeException If the date in this object cannot be
represented in a Java Calendar.
Possible Exceptions Meaning
BrokerOutOfRangeException If the date in this object cannot be
represented in a Java Date.
date_string The string containing the date to set in the
newly created BrokerDate object.
webMethods Broker Client Java API Programmers Guide Version8.2 321
17 Java API Client Reference

"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)
Possible Exceptions Meaning
IllegalArgumentException A parsing error was encountered in the
date_string.
date_string The string containing the date to set in the
newly created BrokerDate object.
locale The locale to be used for the date string.
Possible Exceptions Meaning
IllegalArgumentException A parsing error was encountered in the
date_string.
year The four-digit year, such as 1996 (but less
than 4096.)
mo The one or two-digit month.
17 Java API Client Reference
322 webMethods Broker Client Java API Programmers Guide Version8.2

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
dy The one or two-digit day.
year The four-digit year, such as 1996 (but less
than 4096.)
mo The one or two-digit month.
dy The one or two-digit day.
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.
webMethods Broker Client Java API Programmers Guide Version8.2 323
17 Java API Client Reference

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).
locale The locale to be used for the date string.
17 Java API Client Reference
324 webMethods Broker Client Java API Programmers Guide Version8.2

toString(java.util.Locale.US)
Note: Milliseconds will not appear in the resulting string if they are zero.
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.
Note: Milliseconds will not appear in the resulting string if they are zero.
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
This class contains the following constants.
locale The locale to be used for the date string.
webMethods Broker Client Java API Programmers Guide Version8.2 325
17 Java API Client Reference

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.
17 Java API Client Reference
326 webMethods Broker Client Java API Programmers Guide Version8.2

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.
Possible Exceptions Meaning
BrokerInvalidEventTypeNameException The event_type_name is invalid.
BrokerNoPermissionException The specified client does not have
permission to publish or subscribe to the
event type.
BrokerNullParameterException The event_type_name parameter is null.
BrokerUnknownEventTypeException The client was specified but the event type
is not found on the Broker.
event The event being copied.
Possible Exceptions Meaning
BrokerNullParameterException The event parameter is null.
webMethods Broker Client Java API Programmers Guide Version8.2 327
17 Java API Client Reference

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.
client The Broker client with which this event is
to be associated. If null, the event will not
be type checked.
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.
storage_class The Java class to be instantiated and used
to store the field values for the new event.
Possible Exceptions Meaning
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.
BrokerInvalidEventTypeNameException The event_type_name is invalid.
17 Java API Client Reference
328 webMethods Broker Client Java API Programmers Guide Version8.2

See also: BrokerEvent.fromObject, BrokerEvent.getStorageObject, and BrokerEvent.toObject
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,
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.
client The Broker client with which this event is
to be associated. If null, the event will not
be type checked.
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.
storage_object The object to be used to store the field
values for the new event.
Possible Exceptions Meaning
webMethods Broker Client Java API Programmers Guide Version8.2 329
17 Java API Client Reference

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.
Possible Exceptions Meaning
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.
BrokerInvalidEventTypeNameException The event_type_name is invalid.
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.
17 Java API Client Reference
330 webMethods Broker Client Java API Programmers Guide Version8.2

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
Possible Exceptions Meaning
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.
Possible Exceptions Meaning
BrokerCorruptDataException The data parameter is not a valid
BrokerEvent.
BrokerNoPermissionException Permission to join the client_group was
denied.
BrokerNullParameterException The data parameter is null.
BrokerUnknownEventTypeException The event type does not exist on the
Broker.
webMethods Broker Client Java API Programmers Guide Version8.2 331
17 Java API Client Reference

fromObject
Deprecated. This method has been deprecated for BrokerEvent as support for
ReflectEvent has been dropped in API version 6.5.
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.
Possible Exceptions Meaning
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.
BrokerNullParameterException The obj parameter is null.
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.
17 Java API Client Reference
332 webMethods Broker Client Java API Programmers Guide Version8.2

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
Possible Exceptions Meaning
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.
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.
webMethods Broker Client Java API Programmers Guide Version8.2 333
17 Java API Client Reference

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[]
17 Java API Client Reference
334 webMethods Broker Client Java API Programmers Guide Version8.2

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
Possible Exceptions Meaning
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.
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.
BrokerOutOfRangeException The offset is less than zero, or greater that
the sequence size, or max_n is less than
zero.
webMethods Broker Client Java API Programmers Guide Version8.2 335
17 Java API Client Reference

getBooleanField
See BrokerEvent.get<type>Field.
getBooleanSeqField
See BrokerEvent.get<type>SeqField.
getByteField
See BrokerEvent.get<type>Field.
getByteSeqField
See BrokerEvent.get<type>SeqField.
getCharField
See BrokerEvent.get<type>Field.
getCharSeqField
See BrokerEvent.get<type>SeqField.
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
See BrokerEvent.get<type>Field.
getDateSeqField
See BrokerEvent.get<type>SeqField.
getDoubleField
See BrokerEvent.get<type>Field.
getDoubleSeqField
See BrokerEvent.get<type>SeqField.
getEventId
long getEventId()
17 Java API Client Reference
336 webMethods Broker Client Java API Programmers Guide Version8.2

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.
Possible Exceptions Meaning
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.
BrokerFieldTypeMismatchException The field_name incorrectly accesses a type,
such as using a subscript with a non-
sequence field.
BrokerInvalidFieldNameException The field_name is invalid.
BrokerInvalidTypeException The field is a sequence.
BrokerNullParameterException The field_name parameter is null.
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.
webMethods Broker Client Java API Programmers Guide Version8.2 337
17 Java API Client Reference

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[].
Possible Exceptions Meaning
BrokerFieldNotFoundException 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.
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.
Possible Exceptions Meaning
BrokerFieldNotFoundException Specified field_name does not exist in the
event.
17 Java API Client Reference
338 webMethods Broker Client Java API Programmers Guide Version8.2

See also: BrokerEvent.getField and BrokerEvent
getFloatField
See BrokerEvent.get<type>Field.
getFloatSeqField
See BrokerEvent.get<type>SeqField.
getIntegerField
See BrokerEvent.get<type>Field.
getIntegerSeqField
See BrokerEvent.get<type>SeqField.
getLongField
See BrokerEvent.get<type>Field.
getLongSeqField
See BrokerEvent.get<type>SeqField.
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
Deprecated. This method has been deprecated for BrokerTransactionalClient. However, its
use with BrokerClient is still supported.
long getPublishSequenceNumber()
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.
Possible Exceptions Meaning
webMethods Broker Client Java API Programmers Guide Version8.2 339
17 Java API Client Reference

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.
17 Java API Client Reference
340 webMethods Broker Client Java API Programmers Guide Version8.2

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
Possible Exceptions Meaning
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.
BrokerFieldTypeMismatchException The field_name incorrectly accesses a type,
such as using a subscript with a non-
sequence field.
BrokerInvalidFieldNameException The field_name is invalid.
BrokerInvalidTypeException The field is a sequence of sequences.
BrokerNullParameterException The field_name parameter is null.
BrokerOutOfRangeException The offset is less than zero, or greater that
the sequence size, or max_n is less than
zero.
field_name The name of the sequence field whose
size is to be returned.
Possible Exceptions Meaning
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.
webMethods Broker Client Java API Programmers Guide Version8.2 341
17 Java API Client Reference

getShortField
See BrokerEvent.get<type>Field.
getShortSeqField
See BrokerEvent.get<type>SeqField.
getStorageObject
Deprecated. This method has been deprecated for BrokerEvent as support for ReflectEvent
has been dropped in API version 6.5.
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
See BrokerEvent.get<type>Field.
getStringSeqField
See BrokerEvent.get<type>SeqField.
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.
17 Java API Client Reference
342 webMethods Broker Client Java API Programmers Guide Version8.2

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.
Possible Exceptions Meaning
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.
BrokerFieldTypeMismatchException The field_name incorrectly accesses a type,
such as using a subscript with a non-
sequence field.
BrokerInvalidFieldNameException The field_name is invalid.
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.
webMethods Broker Client Java API Programmers Guide Version8.2 343
17 Java API Client Reference

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.
Possible Exceptions Meaning
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.
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.
BrokerOutOfRangeException The offset is less than zero, or greater that
the sequence size, or max_n is less than
zero.
17 Java API Client Reference
344 webMethods Broker Client Java API Programmers Guide Version8.2

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
See BrokerEvent.get<type>Field.
getUCCharSeqField
See BrokerEvent.get<type>SeqField.
Possible Exceptions Meaning
BrokerFieldNotFoundException The tag envelope field is not set for this
event.
Possible Exceptions Meaning
BrokerInvalidTypeDefException The event is not associated with a Broker
client.
webMethods Broker Client Java API Programmers Guide Version8.2 345
17 Java API Client Reference

getUCStringField
See BrokerEvent.get<type>Field.
getUCStringSeqField
See BrokerEvent.get<type>SeqField.
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.
Possible Exceptions Meaning
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.
17 Java API Client Reference
346 webMethods Broker Client Java API Programmers Guide Version8.2

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
BrokerInvalidFieldNameException The field_name is invalid.
BrokerNullParameterException The field_name parameter is null.
field_name The name of the event field being set.
Possible Exceptions Meaning
webMethods Broker Client Java API Programmers Guide Version8.2 347
17 Java API Client Reference

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.
Possible Exceptions Meaning
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.
BrokerInvalidFieldNameException The field_name is invalid.
17 Java API Client Reference
348 webMethods Broker Client Java API Programmers Guide Version8.2

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
BrokerNullParameterException The field_name parameter is null.
field_name The name of the event field being set.
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[].
Possible Exceptions Meaning
webMethods Broker Client Java API Programmers Guide Version8.2 349
17 Java API Client Reference

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
See BrokerEvent.set<type>Field.
Possible Exceptions Meaning
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.
BrokerInvalidFieldNameException The field_name is invalid.
BrokerNullParameterException The field_name parameter is null.
BrokerOutOfRangeException The src_offset is not within the size of
value, dest_offset is less than zero, or n is
less than zero.
17 Java API Client Reference
350 webMethods Broker Client Java API Programmers Guide Version8.2

setByteSeqField
See BrokerEvent.set<type>SeqField.
setCharField
See BrokerEvent.set<type>Field.
setCharSeqField
See BrokerEvent.set<type>SeqField.
setDateField
See BrokerEvent.set<type>Field.
setDateSeqField
See BrokerEvent.set<type>SeqField.
setDoubleField
See BrokerEvent.set<type>Field.
setDoubleSeqField
See BrokerEvent.set<type>SeqField.
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_name The name of the event field being set.
field_type The type of the field value being set.
value The value for the event field.
webMethods Broker Client Java API Programmers Guide Version8.2 351
17 Java API Client Reference

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.
Possible Exceptions Meaning
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.
BrokerInvalidFieldNameException The field_name is invalid.
BrokerInvalidTypeException The field_type is FIELD_TYPE_SEQUENCE or is
not a supported type.
BrokerNullParameterException The field_name or value parameter is null.
field_name The name of the event field being set.
value The value for the event field.
17 Java API Client Reference
352 webMethods Broker Client Java API Programmers Guide Version8.2

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
See BrokerEvent.set<type>Field.
Possible Exceptions Meaning
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.
BrokerInvalidFieldNameException The field_name is invalid.
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.
webMethods Broker Client Java API Programmers Guide Version8.2 353
17 Java API Client Reference

setFloatSeqField
See BrokerEvent.set<type>SeqField.
setIntegerField
See BrokerEvent.set<type>Field.
setIntegerSeqField
See BrokerEvent.set<type>SeqField.
setLongField
See BrokerEvent.set<type>Field.
setLongSeqField
See BrokerEvent.set<type>SeqField.
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
Deprecated. This method has been deprecated for BrokerTransactionalClient. However, its
use with BrokerClient is still supported.
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.
17 Java API Client Reference
354 webMethods Broker Client Java API Programmers Guide Version8.2

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_name The name of the event field being set.
field_type The type of the field value being set.
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 value for the event field.
Field Name Field Value Type
FIELD_TYPE_BYTE byte[]
webMethods Broker Client Java API Programmers Guide Version8.2 355
17 Java API Client Reference

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
Possible Exceptions Meaning
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.
BrokerInvalidFieldNameException The field_name is invalid.
Field Name Field Value Type
17 Java API Client Reference
356 webMethods Broker Client Java API Programmers Guide Version8.2

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
See BrokerEvent.set<type>Field.
BrokerInvalidTypeException The field_type is FIELD_TYPE_SEQUENCE or is
not a supported field type.
BrokerNullParameterException The field_name parameter 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.
field_name The name of the event field being set.
size The new size for the sequence.
Possible Exceptions Meaning
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.
BrokerInvalidFieldNameException The field_name is invalid.
BrokerNullParameterException The field_name parameter is null.
BrokerOutOfRangeException The size is less than zero.
Possible Exceptions Meaning
webMethods Broker Client Java API Programmers Guide Version8.2 357
17 Java API Client Reference

setShortSeqField
See BrokerEvent.set<type>SeqField.
setStringField
See BrokerEvent.set<type>Field.
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
See BrokerEvent.set<type>SeqField.
field_name The name of the event field being set.
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.
value The value for the event field.
Possible Exceptions Meaning
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.
BrokerInvalidFieldNameException The field_name is invalid.
BrokerNullParameterException The field_name parameter is null.
BrokerOutOfRangeException The offset is not within the size of the
string or if nc would exceed the size of the
string.
17 Java API Client Reference
358 webMethods Broker Client Java API Programmers Guide Version8.2

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.
value The value for the event field.
Possible Exceptions Meaning
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.
BrokerInvalidFieldNameException The field_name is invalid.
BrokerNullParameterException The value parameter is null.
field_name The name of the event field being set.
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.
webMethods Broker Client Java API Programmers Guide Version8.2 359
17 Java API Client Reference

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
See BrokerEvent.set<type>Field.
n Number of source elements. If set to
AUTO_SIZE, all elements of the source array
will be used.
value The array of values for the event field
sequence.
Possible Exceptions Meaning
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.
BrokerInvalidFieldNameException The field_name is invalid.
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.
17 Java API Client Reference
360 webMethods Broker Client Java API Programmers Guide Version8.2

setUCCharSeqField
See BrokerEvent.set<type>SeqField.
setUCStringField
See BrokerEvent.set<type>Field.
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
field_name The name of the event field being set.
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.
value The value for the event field.
Possible Exceptions Meaning
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.
BrokerInvalidFieldNameException The field_name is invalid.
BrokerNullParameterException The field_name parameter is null.
BrokerOutOfRangeException The offset is not within the size of the
string or if nc would exceed the size of the
string.
webMethods Broker Client Java API Programmers Guide Version8.2 361
17 Java API Client Reference

setUCStringSeqField
See BrokerEvent.set<type>SeqField.
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.
17 Java API Client Reference
362 webMethods Broker Client Java API Programmers Guide Version8.2

Invoking this method is equivalent to invoking:
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.
For information on setting formatString, see BrokerFormat.
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.
For information on setting formatString, see BrokerFormat.
Invoking this method is equivalent to invoking:
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.
Invoking this method is equivalent to invoking:
toString(Locale.getDefault());
See also: BrokerEvent.toString
formatString Specifies the format of the output string.
locale The locale to be used for formatting the
string.
formatString Specifies the format of the output string.
webMethods Broker Client Java API Programmers Guide Version8.2 363
17 Java API Client Reference

toObject
Deprecated. This method has been deprecated for BrokerEvent as support for ReflectEvent
has been dropped in API version 6.5.
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.
Possible Exceptions Meaning
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.
BrokerNullParameterException The obj parameter is null.
17 Java API Client Reference
364 webMethods Broker Client Java API Programmers Guide Version8.2

Uses the specified locale to format a string with this event's content that is suitable for
display or printing.
See also: BrokerEvent.toFormattedString and BrokerEvent.toLocalizedString
toString
String toString(
int indent_level)
Returns a string with this event's content, suitable for display or printing.
See also: BrokerEvent.toFormattedString and BrokerEvent.toLocalizedString
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.
See also: BrokerEvent.toFormattedString and BrokerEvent.toLocalizedString
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.
locale The locale to be used for formatting the
string.
indent_level The number of 4-character spaces to use
for indentation.
indent_level The number of 4-character spaces to use
for indentation.
locale The locale to be used for formatting the
string.
client The Broker client context to use for
validation.
webMethods Broker Client Java API Programmers Guide Version8.2 365
17 Java API Client Reference

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.
Possible Exceptions Meaning
BrokerFieldTypeMismatchException The event did not pass validation.
BrokerInvalidClientException The client parameter is null and the event
is not type checked.
Diagnostic Level Description
0 No error output will be produced.
1 Produces error output for major errors only. This is the default
setting
2 Produces all error output for all methods.
17 Java API Client Reference
366 webMethods Broker Client Java API Programmers Guide Version8.2

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.
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 methods. Use this setting when
debugging an application.
webMethods Broker Client Java API Programmers Guide Version8.2 367
17 Java API Client Reference

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.
17 Java API Client Reference
368 webMethods Broker Client Java API Programmers Guide Version8.2

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.
Possible Exceptions Meaning
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.
webMethods Broker Client Java API Programmers Guide Version8.2 369
17 Java API Client Reference

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.
Possible Exceptions Meaning
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.
17 Java API Client Reference
370 webMethods Broker Client Java API Programmers Guide Version8.2

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}
Possible Exceptions Meaning
BrokerFilterRuntimeException A error was encountered while parsing
this filter.
BrokerNullParameterException The event parameter is null.
webMethods Broker Client Java API Programmers Guide Version8.2 371
17 Java API Client Reference

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.
17 Java API Client Reference
372 webMethods Broker Client Java API Programmers Guide Version8.2

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.
Invoking this method is equivalent to invoking:
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.
Possible Exceptions Meaning
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
tokens The list of formatting tokens.
locale The locale to be used for formatting the
string.
Possible Exceptions Meaning
BrokerFieldNotFoundException A field referenced in tokens was not found
in the event
webMethods Broker Client Java API Programmers Guide Version8.2 373
17 Java API Client Reference

See also: BrokerFormat.format, BrokerFormat.formatBindVariable, BrokerFormat.preparse, and
BrokerFormat.setFormatMode
assemble
static String assemble(Vector tokens)
Returns a string assembled from the list of tokens, without an event field reference.
See also: BrokerFormat.format, BrokerFormat.formatBindVariable, BrokerFormat.preparse, and
BrokerFormat.setFormatMode
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.
Invoking this method is equivalent to invoking:
format(event, java.util.Locale.US);
See also: BrokerFormat.assemble, BrokerFormat.formatBindVariable, BrokerFormat.preparse, and
BrokerFormat.setFormatMode
format
String format(
BrokerEvent event,
java.util.Locale locale)
throws BrokerException
BrokerInvalidTypeException A field referenced in tokens is of an
unsupported type.
tokens The list of formatting tokens.
event The event to be formatted.
event The event to be formatted.
Possible Exceptions Meaning
17 Java API Client Reference
374 webMethods Broker Client Java API Programmers Guide Version8.2

Uses the specified locale to return a string containing the field values from event.
See also: BrokerFormat.assemble, BrokerFormat.formatBindVariable, BrokerFormat.preparse, and
BrokerFormat.setFormatMode
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'.
Invoking this method is equivalent to invoking:
format(event, format, java.util.Locale.US);
See also: BrokerFormat.assemble, BrokerFormat.formatBindVariable, BrokerFormat.preparse, and
BrokerFormat.setFormatMode
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'.
See also: BrokerFormat.assemble, BrokerFormat.formatBindVariable, BrokerFormat.preparse, and
BrokerFormat.setFormatMode
locale The locale to be used for formatting the
string.
event The event to be formatted.
format_string The format string to use to format the
event.
event The event to be formatted.
format_string The format string to use to format the
event.
locale The locale to be used for formatting the
string.
webMethods Broker Client Java API Programmers Guide Version8.2 375
17 Java API Client Reference

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.
17 Java API Client Reference
376 webMethods Broker Client Java API Programmers Guide Version8.2

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 :.
webMethods Broker Client Java API Programmers Guide Version8.2 377
17 Java API Client Reference

See also: BrokerFormat.assemble, BrokerFormat.format, BrokerFormat.formatBindVariable, and
BrokerFormat.preparse
BrokerMonitorClient
class 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.
17 Java API Client Reference
378 webMethods Broker Client Java API Programmers Guide Version8.2

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.
Possible Exceptions Description
BrokerInvalidClientException The client has been destroyed.
Possible Exceptions Description
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.
webMethods Broker Client Java API Programmers Guide Version8.2 379
17 Java API Client Reference

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()
Possible Exceptions Description
BrokerInvalidClientException The client has been destroyed.
BrokerIncompatibleVersionException The version of the broker is not known to
this operation.
BrokerNoPermissionException The client has limited acces.s
Possible Exceptions Description
BrokerInvalidClientException The client has been destroyed.
BrokerUnknownServerException A Server is not configured on the
specified port.
Possible Exceptions Description
BrokerInvalidClientException The client has been destroyed.
17 Java API Client Reference
380 webMethods Broker Client Java API Programmers Guide Version8.2

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.
Possible Exceptions Description
BrokerInvalidClientException The client has been destroyed.
BrokerIncompatibleVersionException The version of the broker is not known to
this operation.
BrokerNullParameterException If older_than is null.
BrokerNoPermissionException The client has limited access
Possible Exceptions Description
BrokerInvalidClientException The client has been destroyed.
BrokerUnknownServerException A Server is not configured on the
specified port.
webMethods Broker Client Java API Programmers Guide Version8.2 381
17 Java API Client Reference

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
Possible Exceptions Description
BrokerInvalidClientException The client has been destroyed.
BrokerUnknownServerException A Server is not configured on the
specified port.
17 Java API Client Reference
382 webMethods Broker Client Java API Programmers Guide Version8.2

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
BrokerSSLCertificate()
Creates an empty certificate description.
BrokerSSLCertificate
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.
webMethods Broker Client Java API Programmers Guide Version8.2 383
17 Java API Client Reference

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.
17 Java API Client Reference
384 webMethods Broker Client Java API Programmers Guide Version8.2

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.
indent_level The number of 4-character spaces to use
for indentation.
include_sub_id If set to true, the subscription identifier
will be included in the string.
webMethods Broker Client Java API Programmers Guide Version8.2 385
17 Java API Client Reference

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.
Possible Exceptions Description
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 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.
17 Java API Client Reference
386 webMethods Broker Client Java API Programmers Guide Version8.2

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.
Possible Exceptions Description
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.
Possible Exceptions Description
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.
webMethods Broker Client Java API Programmers Guide Version8.2 387
17 Java API Client Reference

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.
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.
Description copied from class: BrokerClient
Overrides: acknowledge in class BrokerClient
Tags copied from class: BrokerClient
Possible Exceptions Description
BrokerInvalidAcknowledgementExceptio
n
seqn is not a valid event to acknowledge.
BrokerInvalidClientException The client has been destroyed or
disconnected.
BrokerOutOfRangeException seqn is less than zero.
Description copied from class: BrokerClient
Overrides: acknowledge in class BrokerClient
Possible Exceptions Description
17 Java API Client Reference
388 webMethods Broker Client Java API Programmers Guide Version8.2

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.
Tags copied from class: BrokerClient
Possible Exceptions Description
BrokerInvalidAcknowledgementExceptio
n
seqn is not a valid event to acknowledge.
BrokerInvalidClientException The client has been destroyed or
disconnected.
BrokerOutOfRangeException seqn is less than zero.
Description copied from class: BrokerClient
Overrides: acknowledgeThrough in class BrokerClient
Tags copied from class: BrokerClient
Possible Exceptions Description
BrokerInvalidAcknowledgementExceptio
n
seqn is not a valid event to acknowledge.
BrokerInvalidClientException The client has been destroyed or
disconnected.
BrokerOutOfRangeException seqn is less than zero.
external_id A user defined, externally generated
transaction identifier. Can be null.
webMethods Broker Client Java API Programmers Guide Version8.2 389
17 Java API Client Reference

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.
Possible Exceptions Description
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.
Possible Exceptions Description
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.
Possible Exceptions Description
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.
17 Java API Client Reference
390 webMethods Broker Client Java API Programmers Guide Version8.2

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
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.
BrokerNullParameterException tx_clients is null.
Possible Exceptions Description
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.
Possible Exceptions Description
webMethods Broker Client Java API Programmers Guide Version8.2 391
17 Java API Client Reference

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.
Possible Exceptions Description
BrokerInvalidClientException If the client has been destroyed or
disconnected.
BrokerInvalidClientIdException If the destination ID includes invalid
characters.
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.
Possible Exceptions Description
BrokerInvalidClientException If the client has been destroyed or
disconnected.
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.
17 Java API Client Reference
392 webMethods Broker Client Java API Programmers Guide Version8.2

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.
Possible Exceptions Description
BrokerInvalidClientException If the client has been destroyed or
disconnected.
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.
Possible Exceptions Description
BrokerInvalidClientException If the client has been destroyed or
disconnected.
BrokerInvalidEventException If the event was not received from the
Broker.
BrokerNoPermissionException If the client does not have permission to
publish the reply event type.
webMethods Broker Client Java API Programmers Guide Version8.2 393
17 Java API Client Reference

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.
BrokerUnknownEventTypeException If the event type for the reply event does
not exist on the Broker.
Possible Exceptions Description
BrokerInvalidClientException If the client has been destroyed or
disconnected.
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.
Possible Exceptions Description
17 Java API Client Reference
394 webMethods Broker Client Java API Programmers Guide Version8.2

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.
Possible Exceptions Description
BrokerInvalidClientException If the client has been destroyed or
disconnected.
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 event are null.
BrokerUnknownEventTypeException If the event type for the reply event does
not exist on the Broker.
Possible Exceptions Description
BrokerInvalidClientException If the client has been destroyed or
disconnected.
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.
webMethods Broker Client Java API Programmers Guide Version8.2 395
17 Java API Client Reference

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.
Possible Exceptions Description
BrokerInvalidClientException If the client has been destroyed or
disconnected.
BrokerInvalidClientIdException If the destination ID includes invalid
characters.
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.
BrokerOutOfRangeException If the ack_type is not a legal ACK_* value.
BrokerUnknownEventTypeException If the event type for any of the events does
not exist on the Broker.
BrokerInvalidAcknowledgementExceptio
n
If ack_seqn is not a valid event to
acknowledge. Events are not published.
Possible Exceptions Description
17 Java API Client Reference
396 webMethods Broker Client Java API Programmers Guide Version8.2

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.
In addition to the listed exceptions, any communications exception can be thrown.
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.
Possible Exceptions Description
BrokerInterruptedException If interrupt-Get-Events is used to stop the call.
BrokerInvalidClientException If the client has been destroyed or
disconnected.
BrokerOutOfRangeException If msecs is less than -1.
BrokerTimeoutException If the timeout is reached before an event
arrives.
Possible Exceptions Description
BrokerInterruptedException If interrupt-Get-Events is used to stop the call.
BrokerInvalidClientException If the client has been destroyed or
disconnected.
BrokerOutOfRangeException If msecs is less than -1, or max_events is less
than zero.
webMethods Broker Client Java API Programmers Guide Version8.2 397
17 Java API Client Reference

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.
Possible Exceptions Description
BrokerInterruptedException If interrupt-Get-Events is used to stop the call.
BrokerInvalidClientException If the client has been destroyed or
disconnected.
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.
Possible Exceptions Description
17 Java API Client Reference
398 webMethods Broker Client Java API Programmers Guide Version8.2

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
Tags copied from class: BrokerClient
Possible Exceptions Description
BrokerInvalidClientException The client has been destroyed or
disconnected.
BrokerTxClosedException Transaction which has been either
committed or aborted.
webMethods Broker Client Java API Programmers Guide Version8.2 399
17 Java API Client Reference

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,
Possible Exceptions Description
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.
BrokerCommFailureException Problems occur establishing the
connection.
BrokerHostNotFoundException The specified host does not exist.
BrokerInvalidClientIdException The ID contains illegal characters.
BrokerNoPermissionException Permission to join the specified client
group is denied.
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.
17 Java API Client Reference
400 webMethods Broker Client Java API Programmers Guide Version8.2

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
Possible Exceptions Description
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.
BrokerCommFailureException If problems occur establishing the
connection.
BrokerHostNotFoundException If the specified host does not exist.
BrokerInvalidClientIdException If the ID 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_id, 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.
BrokerUnknownClientIdException If the specified client ID does not exist on
the Broker.
webMethods Broker Client Java API Programmers Guide Version8.2 401
17 Java API Client Reference

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.
Possible Exceptions Description
BrokerInvalidTxException The specified transaction does not exist.
BrokerNullParameterException Theexternal_id is null.
tx_id An unique Broker transaction identifier returned by the
beginTransaction method.
Possible Exceptions Description
BrokerInvalidTxException The specified transaction does not exist.
BrokerNullParameterException Thetx_id is null.
tx_clients List of Broker transactional clients.
external_id Externally generated transaction identifier.
17 Java API Client Reference
402 webMethods Broker Client Java API Programmers Guide Version8.2

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.
Possible Exceptions Description
BrokerInvalidTxException The specified transaction does not exist.
BrokerNullParameterException Theexternal_id or tx_clients is null.
tx_client Broker transactional client.
external_ids List of externally created transaction identifiers.
Possible Exceptions Description
BrokerInvalidTxException The specified transaction does not exist.
BrokerNullParameterException Theexternal_id or tx_clients is null.
Overrides: publish in class BrokerClient
Possible Exceptions Description
BrokerInvalidClientException If the client has been destroyed or
disconnected.
BrokerInvalidEventException If the event does not match its type
definition.
BrokerNoPermissionException If the client does not have permission to
publish the event type.
webMethods Broker Client Java API Programmers Guide Version8.2 403
17 Java API Client Reference

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
Possible Exceptions Description
BrokerInvalidClientException If the client has been destroyed or
disconnected.
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 events is 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.
Overrides: publishWithAck in class BrokerClient
Possible Exceptions Description
17 Java API Client Reference
404 webMethods Broker Client Java API Programmers Guide Version8.2

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.
Possible Exceptions Description
BrokerInvalidClientException If the client has been destroyed or
disconnected.
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 events is null, or if any element in the
array is null.
BrokerOutOfRangeException If the ack_type is not a legal ACK_* value.
BrokerUnknownEventTypeException If the event type for any of the events does
not exist on the Broker.
BrokerInvalidAcknowledgementExceptio
n
If ack_seqn if not a valid event to
acknowledge. Events are not published.
Possible Exceptions Description
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.
BrokerCommFailureException If problems occur establishing the
connection.
BrokerHostNotFoundException If the specified host does not exist.
BrokerNoPermissionException If permission to join the specified client
group is denied.
webMethods Broker Client Java API Programmers Guide Version8.2 405
17 Java API Client Reference

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.
BrokerNotRunningException If the host exists but no Broker is running
on that host.
BrokerNullParameterException If broker_host or client_id 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.
BrokerUnknownClientIdException If the specified client ID does not exist on
the Broker.
Possible Exceptions Description
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.
BrokerCommFailureException If problems occur establishing the
connection.
BrokerHostNotFoundException If the specified host does not exist.
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 or client_id are null.
Possible Exceptions Description
17 Java API Client Reference
406 webMethods Broker Client Java API Programmers Guide Version8.2

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.
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.
BrokerUnknownClientIdException If the specified client ID does not exist on
the Broker.
client The client whose type definition cache is
to be flushed.
Possible Exceptions Description
webMethods Broker Client Java API Programmers Guide Version8.2 407
17 Java API Client Reference

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
This class contains the following constants.
Possible Exceptions Meaning
BrokerInvalidClientException The client has been destroyed or
disconnected.
17 Java API Client Reference
408 webMethods Broker Client Java API Programmers Guide Version8.2

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.
webMethods Broker Client Java API Programmers Guide Version8.2 409
17 Java API Client Reference

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
Possible Exceptions Meaning
BrokerInvalidTypeException The event is not valid.
field_name The name of a field within the event.
Possible Exceptions Meaning
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.
BrokerInvalidFieldNameException The field_name is invalid.
17 Java API Client Reference
410 webMethods Broker Client Java API Programmers Guide Version8.2

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.
Possible Exceptions Meaning
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.
BrokerInvalidFieldNameException The field_name is invalid.
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.
webMethods Broker Client Java API Programmers Guide Version8.2 411
17 Java API Client Reference

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.
Possible Exceptions Meaning
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.
BrokerInvalidFieldNameException The field_name is invalid.
Possible Exceptions Meaning
BrokerInvalidTypeException The event is not valid.
17 Java API Client Reference
412 webMethods Broker Client Java API Programmers Guide Version8.2

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.
Possible Exceptions Meaning
BrokerInvalidTypeException The event is not valid.
indent_level The number of 4-character spaces to use
for indentation.

webMethods Broker Client Java API Programmers Guide Version8.2 413
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.
BrokerClientExistsException
The 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.
BrokerFailureException
An 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
414 webMethods Broker Client Java API Programmers Guide Version8.2

BrokerFieldNotFoundException
An attempt was made to operate on a BrokerEvent field that does not exist.
BrokerFieldTypeMismatchException
The 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.
BrokerFileNotFoundException
The specified file could not be found or could not be opened.
BrokerFilterParseException
An error occurred while parsing the filter string specified when creating a new BrokerFilter.
BrokerFilterRuntimeException
The filter specified with the BrokerFilter.matchFilter method caused a runtime error, such as
division by zero.
BrokerFormatException
This can result from some protocol failures. It is mainly issued by the BrokerString calls to
parse values out of strings.
BrokerHostNotFoundException
The host specified when creating or reconnecting a BrokerClient could not be found.
BrokerIncompatibleVersionException
The Broker is running an older version of the product than this API.
BrokerInterruptedException
A 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.
BrokerInvalidAcknowledgementException
An attempt was made to acknowledge a sequence number that was out of order or which
was not been assigned to your Broker client.
BrokerInvalidClassException
The storage_class passed to the BrokerEvent constructor could not be instantiated using the
class' newInstance method.
BrokerInvalidClientException
The BrokerClient object passed to the method is either disconnected or has been destroyed.
BrokerInvalidClientIdException
The client ID specified when creating a new BrokerClient contained illegal characters or was
longer than 255 characters.
BrokerInvalidDescriptorException
The BrokerConnectionDescriptor object passed to the method has been deleted.
BrokerInvalidEventException
The BrokerEvent object passed to the method has been deleted.
webMethods Broker Client Java API Programmers Guide Version8.2 415
A API Exceptions

BrokerInvalidEventTypeNameException
An 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.
BrokerInvalidFieldNameException
A 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.
BrokerInvalidPlatformKeyException
An invalid platform key was specified.
BrokerInvalidSubscriptionException
A 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.
BrokerInvalidTypeCacheException
An internal error occurred with the event type definition cache. This does not represent a
user error.
BrokerInvalidTypeDefException
The 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.
BrokerInvalidTypeException
An 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.
BrokerNoPermissionException
You 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.
BrokerNotImplementedException
The method you requested is not implemented.
A API Exceptions
416 webMethods Broker Client Java API Programmers Guide Version8.2

BrokerNotRunningException
While attempting to create or reconnect a BrokerClient, the specified host was found but no
Broker was running on that host.
BrokerNullParamException
A null value was passed for a parameter that requires a value.
BrokerOutOfRangeException
A parameter value is outside the accepted range. For example, getting a sequence subset
using negative indexes will cause this exception to be thrown.
BrokerPublishPauseException
An internal failure occurred while communicating with the Broker.
BrokerProtocolException
An internal failure occurred while communicating with the Broker.
BrokerSecurityException
A security problem occurred that prevented the operation from being completed.
BrokerSubscriptionExistsException
You attempted to create a new BrokerSubscription with an event type and filter that has
already been used for another subscription.
BrokerTimeoutException
The requested operation timed out. This occurs for methods like BrokerClient.getEvent when
an event is not received within the specified time-out interval.
BrokerTxClosedException
Action attempted on a BrokerClient transaction that has already been either committed
or aborted.
BrokerUnknownBrokerNameException
The Broker specified when reconnecting or creating a new BrokerClient was not found.
BrokerUnknownClientGroupException
The client group specified when reconnecting or creating a new BrokerClient was not
found.
BrokerUnknownClientIdException
The Client ID specified when reconnecting a BrokerClient was not found.
BrokerUnknownEventTypeException
The 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.
BrokerUnknownInfosetException
The specified infoset was not found for the event type.
BrokerUnknownKeyException
The platform specified key for BrokerClient.getPlatformInfo has no value defined.
BrokerUnknownNameException
The specified distinguished name does not exist in the appropriate SSL certificate file.
webMethods Broker Client Java API Programmers Guide Version8.2 417
A API Exceptions

BrokerUnknownTxException
Specified name does not exist in the resource being accessed.
A API Exceptions
418 webMethods Broker Client Java API Programmers Guide Version8.2


webMethods Broker Client Java API Programmers Guide Version8.2 419
B Parameter Naming Rules
Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 420
Length Restriction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 420
Restricted Characters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 420
Reserved Words . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 421
System Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 421
webMethods Broker Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 421
B Parameter Naming Rules
420 webMethods Broker Client Java API Programmers Guide Version8.2

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.
webMethods Broker Client Java API Programmers Guide Version8.2 421
B Parameter Naming Rules

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.
B Parameter Naming Rules
422 webMethods Broker Client Java API Programmers Guide Version8.2

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.