8-2-SP1 Broker Java Admin Programmers Guide
-
Upload
muniraghunath -
Category
Documents
-
view
507 -
download
3
Transcript of 8-2-SP1 Broker Java Admin Programmers Guide
Title Page
webMethods Broker Administration Java APIProgrammer’s Guide
Version 8.2
April 2011
This document applies to webMethods Broker Version 8.2 and to all subsequent releases.
Specifications contained herein are subject to change and these changes will be reported in subsequent release notes or new editions.
Copyright © 2001-2011 Software AG, Darmstadt, Germany and/or Software AG USA, Inc., Reston, VA, United States of America, and/or their licensors.
Detailed information on trademarks and patents owned by Software AG and/or its subsidiaries is located at http://documentation.softwareag.com/legal/.
Use of this software is subject to adherence to Software AG's licensing conditions and terms. These terms are part of the product documentation, located at http://documentation.softwareag.com/legal/ and/or in the root installation directory of the licensed product(s).
This software may include portions of third-party products. For third-party copyright notices and license terms, please refer to “License Texts, Copyright Notices and Disclaimers of Third-Party Products”. This document is part of the product documentation, located at http://documentation.softwareag.com/legal/and/or in the root installation directory of the licensed product(s).
Document ID: BR-ADMINJAVAAPI-PG-82SP1-20110401
Table of Contents
About this Guide . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29Document Conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29Documentation Installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30Online Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30
1. Managing Broker Event Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34Understanding the BrokerAdminTypeDef . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34Listing Event Type Definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35
Getting Multiple Event Type Definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36Getting Event Type Definitions by Scope . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36
Getting Event Type Statistics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37Creating and Modifying Event Type Definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37
Modifying Event Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38Creating or Modifying Multiple Event Type Definitions . . . . . . . . . . . . . . . . . . . . . . . . . 39
Destroying Event Type Definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39Destroying Multiple Event Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39
Event Type Infosets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40Setting Event Type Infosets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40Creating or Modifying Multiple Infosets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40
Destroying Infosets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40Destroying Multiple Infosets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41
2. Getting Started . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44Overview of the webMethods Broker Administration API . . . . . . . . . . . . . . . . . . . . . . . . . . 44
BrokerServerClient . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45BrokerAdminClient . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46Monitoring Brokers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46Managing Security Configurations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46Managing Territories . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46Managing Clusters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47Managing Configurations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47
Using the Administration API for Java . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47Compatibility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47Application Development with webMethods Broker . . . . . . . . . . . . . . . . . . . . . . . . . . . 47Application Deployment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48
webMethods Broker Java API Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48
3. Managing Brokers and Broker Servers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50
webMethods Broker Administration Java API Programmer’s Guide Version 8.2 3
Understanding Broker Server Clients . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50Creating a BrokerServerClient . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50Destroying a BrokerServerClient . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51Connection Notification . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51
Defining a Callback Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51Registering the Callback Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51Un-Registering Callback Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52
Managing a Broker Server Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52Getting Broker Server Statistics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52Getting System Usage Statistics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53Getting and Setting the Default Broker . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53Getting and Setting Log Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54Getting the Port Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54Getting and Setting the License . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55Starting and Stopping the Host Process . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55Managing Security Configurations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55
Managing Brokers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55Using Change Locks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55Listing all Brokers on a Host . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56Creating and Destroying Brokers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57
4. Managing Broker Clients . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60Understanding BrokerAdminClients . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60
Creating a BrokerAdminClient . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60Destroying a BrokerAdminClient . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62Using Multiple BrokerAdminClients . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62Disconnecting a BrokerAdminClient . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63Reconnecting a BrokerAdminClient . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63
Using the newOrReconnectAdmin Method . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64Broker Administration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64
Destroying a Broker . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64Getting and Setting the Broker Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65Getting Broker Statistics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65
Broker Client Administration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66Obtaining Broker Client Identifiers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66Getting Broker Client Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67Creating Broker Clients . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68Reconnecting a Remote Broker . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68Disconnecting Broker Clients . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68Disconnecting by Session Identifier . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69Destroying Broker Clients . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70Client State Sharing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70Setting the Last-published Sequence Number . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70Clearing a Broker Client's Queue . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71
4 webMethods Broker Administration Java API Programmer’s Guide Version 8.2
Broker Client Subscriptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71Listing Subscriptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71Testing the Existence of a Subscription . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71Creating Subscriptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71Destroying Subscriptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72
Getting Broker Client Statistics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72Getting Broker Client Infosets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73
5. Managing Client Groups . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76Listing Client Groups . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76Listing Client Identifiers by Group . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77Getting Client Group Statistics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77Creating and Destroying Client Groups . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78
Life Cycle . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78Storage Type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79Setting Client Group Descriptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79Destroying Client Groups . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79
BrokerClientGroupInfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80Controlling Event Publications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80Controlling Event Subscriptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81Controlling Group Access . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82
6. Managing Security Configurations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84Access Control Lists . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84
Getting and Setting Authenticator Names . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85Getting and Setting Names . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85Converting to a String . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86
Broker Server Security Configurations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86Retrieving and Setting Broker Server Security Configurations . . . . . . . . . . . . . . . . . . . 86Retrieving and Setting Broker Server ACLs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87
Client Group Security Configurations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87Obtaining Security Information for Client Sessions . . . . . . . . . . . . . . . . . . . . . . . . . . . 87
Territory Security Configurations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88Setting Territory Security . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88Territory ACLs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88
Territory Gateway Security Configurations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89Setting Territory Security . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89Territory Gateway ACLs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89
Cluster Security Configurations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89Setting Cluster Security . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89Cluster ACLs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90
Cluster Gateway Security Configurations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90Setting Cluster Security . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90
webMethods Broker Administration Java API Programmer’s Guide Version 8.2 5
Cluster Gateway ACLs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91
7. Managing Broker Territories . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94Using Territories . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94
Creating a New Territory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94Adding a Broker to an Existing Territory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95Removing a Broker from a Territory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95Getting Territory Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95Listing Brokers in a Territory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 96Obtaining Territory Statistics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 96Maintaining a Connection Between Brokers in a Territory . . . . . . . . . . . . . . . . . . . . . . 96
Activating the Keep-Alive Feature between Territory Brokers . . . . . . . . . . . . . . . . 96Checking the Keep-Alive Settings for a Broker . . . . . . . . . . . . . . . . . . . . . . . . . . . 97
Setting Territory Security . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97Using Territory Gateways . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97
Creating and Destroying Gateways . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98Setting Shared Event Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99Listing Local Gateways . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99Listing All Gateways . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99Managing Event Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99Obtaining Gateway Statistics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100Maintaining a Connection Between Gateway Brokers . . . . . . . . . . . . . . . . . . . . . . . . . 100
Activating the Keep-Alive Feature between Gateway Brokers . . . . . . . . . . . . . . . 100Checking the Keep-Alive Settings for a Gateway Broker . . . . . . . . . . . . . . . . . . . 101
Pausing a Gateway Broker . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101Pausing Traffic in Both Directions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101Pausing Traffic to and from Multiple Territories . . . . . . . . . . . . . . . . . . . . . . . . . . . 101Unpausing a Gateway Broker . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102Checking the Current Pause Setting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102
Static Gateway Forwarding . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102Refusing Document Type Updates Across a Gateway . . . . . . . . . . . . . . . . . . . . . . . . . 102
Update Refusal Classes and Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103Synchronizing Updates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103
Setting Territory Gateway Security . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104
8. Managing Broker Clusters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 105Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 106Using Clusters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 106
Creating a New Cluster . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 106Adding a Broker to an Existing Cluster . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 106Removing a Broker from a Cluster . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107Getting Cluster Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107Listing Brokers in a Cluster . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107Obtaining Cluster Statistics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107
6 webMethods Broker Administration Java API Programmer’s Guide Version 8.2
Maintaining a Connection Between Brokers in a Cluster . . . . . . . . . . . . . . . . . . . . . . . 108Activating the Keep-Alive Feature between Cluster Brokers . . . . . . . . . . . . . . . . . 108Checking the Keep-Alive Settings for a Broker . . . . . . . . . . . . . . . . . . . . . . . . . . . 108
Setting Cluster Security . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 108Using Cluster Gateways . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109
Creating and Destroying Cluster Gateways . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109Setting Shared Event Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109Setting Primary Gateway . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 110Listing Local Gateways . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 110Listing All Gateways . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 110Managing Event Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 110Obtaining Gateway Statistics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111Maintaining a Connection Between Gateway Brokers . . . . . . . . . . . . . . . . . . . . . . . . . 111
Activating the Keep-Alive Feature between Gateway Brokers . . . . . . . . . . . . . . . 111Checking the Keep-Alive Settings for a Cluster Gateway Broker . . . . . . . . . . . . . 112
Pausing a Gateway Broker . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112Pausing Traffic in Both Directions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112Pausing Traffic to and from Multiple Clusters . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113Unpausing a Cluster Gateway Broker . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113Checking the Current Pause Setting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113
Static Gateway Forwarding . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113Refusing Document Type Updates Across a Gateway . . . . . . . . . . . . . . . . . . . . . . . . 114
Update Refusal Classes and Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114Synchronizing Updates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114
Setting Cluster Gateway Security . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115
9. Managing Site Configurations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 118Collection Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 118Server Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 118Broker Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 119Client Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 120Client Group Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121Event Type Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122Territory Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122Territory Gateway Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123
10. Monitoring Broker Activity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 126Activity and Trace Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 126
Activity Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 126Client Changes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 127Client Group Changes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 127Event Type Changes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 128Territory Changes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 128
webMethods Broker Administration Java API Programmer’s Guide Version 8.2 7
Trace Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 129Dropped Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 129Remotely Dropped Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 130Enqueued Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 130Remotely Enqueued Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131Published Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131Remotely Published Event . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132Received Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132Remotely Received Event . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 133Peek Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 133Insert Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 134Delete Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 134
Activity Traces . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 134Understanding the BrokerTraceEvent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 135Obtaining Activity Traces . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 135
Broker Logging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 135Understanding the BrokerLogConfig . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 136Understanding the BrokerLogEntry . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 137
Broker Server Logs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 137Obtaining Log Entries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 137Obtaining Log Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 138Deleting Log Entries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 138
11. Queue Browser . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 139Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 140Client Queue Browser . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 140Using Client Queue Browser . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 141Forwarding Queue Browser . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 142Using Forwarding Queue Browser . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 144BrokerAdminClient . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 145BrokerClient . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 145BrokerQueueBrowser and BrokerClientQueueBrowser . . . . . . . . . . . . . . . . . . . . . . . . . . . . 146BrokerLockedQueueBrowser and BrokerLockedClientQueueBrowser . . . . . . . . . . . . . . . . 147Creating and Closing Client Queue Browsers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 148
For a Client Queue Browser . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 148For an Administrative Queue Browser With No Lock . . . . . . . . . . . . . . . . . . . . . . . . . . 149For a Administrative Queue Browser With a Lock . . . . . . . . . . . . . . . . . . . . . . . . . . . . 150
Creating and Closing Forwarding Queue Browsers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 151For an Administrative Queue Browser With No Lock . . . . . . . . . . . . . . . . . . . . . . . . . . 152
Acquiring a Queue Lock . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 153Releasing a Queue Lock . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 153Queue Position . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 153Filters on a Queue Browser . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 154
Setting a Single Filter on Queue Browser . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 155Setting Multiple Filters on Queue Browser . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 155
8 webMethods Broker Administration Java API Programmer’s Guide Version 8.2
Resetting Filters on Queue Browser . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 156Viewing Currently Set Filters on Queue Browser . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 157
Viewing Queue Content . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 158Viewing a Client's Own Queue Content . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 158Administratively Viewing Contents of an Unlocked Client Queue . . . . . . . . . . . . . . . . 159Administratively Viewing Contents of a Locked Client Queue . . . . . . . . . . . . . . . . . . . 161Administratively Viewing Contents of an Unlocked Forwarding Queue . . . . . . . . . . . . 162Administratively Viewing Contents of a Locked Forwarding Queue . . . . . . . . . . . . . . . 164Identifying "Unacknowledged" Documents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 165
Rearranging Queue Content . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 166Modifying Documents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 166Inserting Documents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 168Deleting Documents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 169Unblocking the Forwarding Queue in a Territory or Cluster . . . . . . . . . . . . . . . . . . . . . 170Unblocking the Forwarding Queue in a Territory Gateway or Cluster Gateway . . . . . . 171
12. Java API Administration Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 173AccessControlList . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 175
Constructors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 175BrokerAccessControlList . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 175BrokerAccessControlList . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 175
Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 175getAuthNames . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 175getAuthNameState . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 175getUserNames . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 176getUserNameState . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 176setAuthNames . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 176setAuthNameState . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 177setAuthNameStates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 177setUserNames . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 178setUserNameState . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 178setUserNameStates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 179toString . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 179toString . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 180
BrokerAdminClient . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 180Constants . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 180Constructor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 180
BrokerAdminClient . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 180Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 182
abort Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 182abortForced . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 182abortForced . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 183
acquire Method . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 183acquireChangeLock . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 183
add Method . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 184
webMethods Broker Administration Java API Programmer’s Guide Version 8.2 9
addBrokerToCluster . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 184check Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 185
checkAndRestartForwarding . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 185checkAndRestartForwarding . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 185
clear Method . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 186clearClientQueueById . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 186
commit Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 186commitForced . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 186commitForced . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 187
create Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 187createClient . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 187createClientGroup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 188createClientQueueBrowser . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 189createClientSubscriptionById . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 190createClientSubscriptionsById . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 191createCluster . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 192createClusterGateway . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 193createForwardQueueBrowser . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 194createLockedClientQueueBrowser . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 195createLockedForwardQueueBrowser . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 195createTerritory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 196createTerritoryGateway . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 197
delete Method . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 198deleteLogEvents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 198
destroy Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 198destroyBroker . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 198destroyClientById . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 199destroyClientGroup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 199destroyClientSubscriptionById . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 200destroyClientSubscriptionsById . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 201destroyClusterGateway . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 202destroyEventType . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 203destroyEventTypeInfoset . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 204destroyEventTypeInfosets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 204destroyEventTypes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 205destroyTerritoryGateway . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 206
disconnect Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 207disconnectClientById . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 207disconnectClientSessionById . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 208
does Method . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 208doesClientSubscriptionExistById . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 208
forget Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 209forgetForced . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 209forgetForced . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 210forgetForced . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 210
10 webMethods Broker Administration Java API Programmer’s Guide Version 8.2
get Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 210getActivityTraces . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 210getAllClusterGateways . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 211getAllQueueStats . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 211getAllTerritoryGateways . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 213getBrokerDescription . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 213getBrokersInCluster . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 214getBrokersInTerritory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 214getBrokerStats . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 215getClientGroupACL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 217getClientGroupCanPublishList . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 217getClientGroupCanSubscribeList . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 218getClientGroupInfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 218getClientGroupInfos . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 219getClientGroupLogAcknowledgeList . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 219getClientGroupLogPublishList . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 220getClientGroupNames . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 220getClientGroupStats . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 221getClientGroupsWhichCanPublish . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 221getClientGroupsWhichCanSubscribe . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 222getClientIds . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 223getClientIdsByClientGroup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 223getClientIdsWhichAreSubscribed . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 224getClientInfoById . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 224getClientInfosById . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 225getClientInfosetById . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 225getClientQueueBrowsers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 226getClientQueueLock . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 226getClientStatsById . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 227getClientSubscriptionsById . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 228getClusterACL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 229getClusterGatewayACL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 229getClusterGatewayKeepAlive . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 230getClusterGatewayRefuseAllUpdates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 231getClusterGatewaySharedEventTypes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 231getClusterGatewayStats . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 232getClusterInfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 235getClusterStaticGatewayForwarding . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 235getClusterStats . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 236getEventAdminTypeDef . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 239getEventAdminTypeDefs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 239getEventAdminTypeDefsByScope . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 240getEventLogging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 241getEventTypeStats . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 241getHeuristicTransactions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 242
webMethods Broker Administration Java API Programmer’s Guide Version 8.2 11
getLocalClusterGateways . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 243getLocalTerritoryGateways . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 244getLogEvents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 244getLogLength . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 245getPostPrepareTimeout . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 245getPostPrepareTimeoutAction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 245getPrePrepareTimeout . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 246getRecoverMode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 246getRemoteBrokerKeepAlive . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 246getStaticGatewayForwarding . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 247getTerritoryACL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 247getTerritoryGatewayACL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 248getTerritoryGatewayKeepAlive . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 248getTerritoryGatewayRefuseAllUpdates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 249getTerritoryGatewayRefuseEventTypeUpdates . . . . . . . . . . . . . . . . . . . . . . . 250getTerritoryGatewaySharedEventTypes . . . . . . . . . . . . . . . . . . . . . . . . . . . . 250getTerritoryGatewayStats . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 251getTerritoryInfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 254getTerritoryStats . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 255getTransactions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 258getTransactionsByClient . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 259
join method . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 260joinTerritory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 260
leave Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 261leaveCluster . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 261leaveTerritory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 262
new Method . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 263newOrReconnectAdmin . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 263
reconnect Method . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 264reconnectAdmin . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 264
release Method . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 266releaseChangeLock . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 266
remove Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 266removeBrokerFromCluster . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 266removeBrokerFromTerritory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 267
set Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 268setBrokerDescription . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 268setClientGroupAccessLabelRequired . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 269setClientGroupACL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 270setClientGroupCanPublishList . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 270setClientGroupCanSubscribeList . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 271setClientGroupDescription . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 272setClientGroupLogAcknowledgeList . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 273setClientGroupLogPublishList . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 273setClientGroupRequiredEncryption . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 274
12 webMethods Broker Administration Java API Programmer’s Guide Version 8.2
setClientInfosetById . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 274setClientLastPublishSequenceNumberById . . . . . . . . . . . . . . . . . . . . . . . . . . 275setClientStateShareLimitById . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 276setClusterACL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 277setClusterGatewayACL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 278setClusterGatewayKeepAlive . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 279setClusterGatewayPause . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 280setClusterGatewayRefuseAllUpdates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 281setClusterGatewaySecurity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 281setClusterGatewaySharedEventTypes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 282setClusterPrimaryGateway . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 284setClusterSecurity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 284setClusterStaticGatewayForwarding . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 285setEventAdminTypeDef . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 286setEventAdminTypeDefs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 286setEventLogging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 287setEventTypeInfoset . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 287setEventTypeInfosets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 288setEventTypesAndClientGroups . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 289setPostPrepareTimeout . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 291setPostPrepareTimeoutAction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 291setPrePrepareTimeout . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 292setRecoverMode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 292setRemoteBrokerKeepAlive . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 293setStaticGatewayForwarding . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 294setTerritoryACL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 294setTerritoryGatewayACL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 295setTerritoryGatewayKeepAlive . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 296setTerritoryGatewayPause . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 297setTerritoryGatewayRefuseAllUpdates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 298setTerritoryGatewayRefuseEventTypeUpdates . . . . . . . . . . . . . . . . . . . . . . . 298setTerritoryGatewaySecurity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 299setTerritoryGatewaySharedEventTypes . . . . . . . . . . . . . . . . . . . . . . . . . . . . 300setTerritorySecurity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 301
BrokerAdminTypeDef . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 302Constructors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 303
BrokerAdminTypeDef . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 303BrokerAdminTypeDef . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 303BrokerAdminTypeDef . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 304BrokerAdminTypeDef . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 304
Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 305clearField . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 305clearFields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 305clearModificationFlag . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 305getBaseTypeName . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 305
webMethods Broker Administration Java API Programmer’s Guide Version 8.2 13
getDescription . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 306getFieldDef . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 306getFieldNames . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 306getFieldType . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 307getScopeTypeName . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 307getStorageType . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 308getTimeToLive . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 308getTypeName . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 308hasBeenModified . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 308insertFieldDef . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 309isSystemDefined . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 309orderFields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 310renameField . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 310setDescription . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 311setFieldDef . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 312setFieldType . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 312setModificationFlag . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 313setStorageType . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 313setTimeToLive . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 313setTypeName . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 314toString . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 314toString . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 315
BrokerAuthInfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 315Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 315
username . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 315authenticator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 315
Constructors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 315BrokerAuthInfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 315BrokerAuthInfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 316BrokerAuthInfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 316
Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 316getAuthenticator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 316getUserName . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 316setAuthenticator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 316setUserName . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 316toString . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 317toString . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 317
BrokerChangeLockInfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 317Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 317
acquired . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 317client_id . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 317session_id . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 317lock_time . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 318
BrokerClientGroupInfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 318Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 318
14 webMethods Broker Administration Java API Programmer’s Guide Version 8.2
access_label_required . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 318description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 318is_system_defined . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 318life_cycle . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 318name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 318required_encryption . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 318storage_type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 319
Constructors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 319BrokerClientGroupInfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 319BrokerClientGroupInfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 319
Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 320toString . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 320toString . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 320
BrokerClientInfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 320Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 320
access_label . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 320app_name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 320authenticator_name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 320can_share_state . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 320client_group . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 321client_id . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 321high_pub_seqn . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 321sessions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 321shared_event_ordering . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 321state_share_limit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 321user_name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 321
Constructors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 322BrokerClientInfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 322BrokerClientInfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 322
Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 322toCompleteString . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 322toString . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 322toString . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 323
BrokerClientQueueBrowser . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 323Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 323
browseEvents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 323closeQueueBrowser . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 324getBrowserInfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 324getFilters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 324resetFilters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 325setFilter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 325setFilters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 325setPosition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 326
BrokerClientQueueBrowserInfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 326Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 326
webMethods Broker Administration Java API Programmer’s Guide Version 8.2 15
clientId . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 326browserId . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 326browserSessionId . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 327locked . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 327createTime . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 327
Constructors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 327BrokerClientQueueBrowserInfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 327BrokerClientQueueBrowserInfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 327
BrokerClientSession . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 327Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 328
auth_info . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 328auth_protocol . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 328auth_version . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 328connect_time . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 328connection_id . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 328create_time . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 328encrypt_level . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 328encrypt_protocol . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 328encrypt_version . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 329ip_address . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 329last_activity_time . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 329platform_info . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 329port . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 329session_id . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 329ssl_certificate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 329
Constructors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 329BrokerClientSession . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 329BrokerClientSession . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 330
Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 330toString . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 330
BrokerClusterGatewayInfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 331Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 331
accessible_clusters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 331auth_type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 331encrypt_level . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 331gateway_broker_name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 331gateway_host_name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 331is_complete . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 331is_local . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 332is_primary_gateway . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 332remote_broker_description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 332remote_broker_name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 332remote_cluster_name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 332remote_host_name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 332
Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 332
16 webMethods Broker Administration Java API Programmer’s Guide Version 8.2
toString . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 332toString . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 333
BrokerClusterInfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 333Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 333
auth_type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 333cluster_name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 333encrypt_level . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 333isLocalPublish . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 333
Constructor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 334BrokerClusterInfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 334BrokerClusterInfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 334
Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 334toString . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 334toString . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 334
BrokerCompleteBroker . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 334Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 334
broker_name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 334brokers_in_territory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 335client_groups . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 335clients . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 335description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 335event_types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 335is_default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 335territory_name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 335
Constructors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 335BrokerCompleteBroker . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 335BrokerCompleteBroker . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 336
Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 336deepRefresh . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 336deepRetrieve . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 336deepStore . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 337refresh . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 338retrieve . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 338store . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 339toString . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 339toString . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 340write . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 340
BrokerCompleteClient . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 340Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 341
client_info . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 341infoset . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 341replace_subscriptions_on_store . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 341subscriptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 341
Constructors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 341BrokerCompleteClient . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 341
webMethods Broker Administration Java API Programmer’s Guide Version 8.2 17
BrokerCompleteClient . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 341Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 342
refresh . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 342retrieve . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 342store . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 343toString . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 344toString . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 344write . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 345
BrokerCompleteClientGroup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 345Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 345
acl . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 345can_publish . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 346can_subscribe . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 346client_group_info . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 346ignore_change_errors_on_store . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 346replace_lists_on_store . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 346
Constructors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 346BrokerCompleteClientGroup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 346BrokerCompleteClientGroup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 346
Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 347refresh . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 347retrieve . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 347store . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 348toString . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 349toString . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 349write . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 349
BrokerCompleteCollection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 350Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 350
acls . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 350brokers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 350client_groups . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 350clients . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 350event_types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 351servers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 351
Constructors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 351BrokerCompleteCollection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 351
Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 351read . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 351readFile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 352toString . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 352toString . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 352write . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 353writeVersionNumber . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 353
BrokerCompleteEventType . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 354Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 354
18 webMethods Broker Administration Java API Programmer’s Guide Version 8.2
infosets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 354replace_infosets_on_store . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 354type_def . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 354
Constructors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 355BrokerCompleteEventType . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 355BrokerCompleteEventType . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 355
Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 355refresh . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 355retrieve . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 356store . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 356toString . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 357toString . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 357write . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 358
BrokerCompleteServer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 358Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 358
acl . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 358brokers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 358description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 358host_name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 359license_key . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 359log_config . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 359port . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 359ssl_config . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 359
Constructors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 359BrokerCompleteServer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 359
Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 359deepRefresh . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 359deepRetrieve . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 360deepStore . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 361refresh . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 363retrieve . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 363store . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 364toString . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 365toString . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 365write . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 365
BrokerCompleteTerritory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 366Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 366
acl . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 366info . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 366other_brokers_in_territory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 366
Constructors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 366BrokerCompleteTerritory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 366BrokerCompleteTerritory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 366
Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 367refresh . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 367
webMethods Broker Administration Java API Programmer’s Guide Version 8.2 19
retrieve . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 367store . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 368toString . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 368toString . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 368write . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 369
BrokerCompleteTerritoryGateway . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 369Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 370
acl . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 370info . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 370remote_can_publish . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 370
Constructors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 370BrokerCompleteTerritoryGateway . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 370BrokerCompleteTerritory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 370
Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 371refresh . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 371retrieve . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 371store . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 372toString . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 373toString . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 373write . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 374
BrokerFilterDescriptor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 374Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 374
eventTypeName . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 374filterExpr . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 374
Constructors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 375BrokerFilterDescriptor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 375BrokerFilterDescriptor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 375
Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 375toString . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 375
BrokerForwardQueueBrowser . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 375Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 375
browseEvents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 375closeQueueBrowser . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 376getBrowserInfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 376getFilters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 376resetFilters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 377setFilter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 377setFilters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 377setPosition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 378
BrokerInfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 378Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 378
broker_host . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 378broker_name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 378cluster_name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 378description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 379
20 webMethods Broker Administration Java API Programmer’s Guide Version 8.2
territory_name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 379Constructors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 379
BrokerInfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 379BrokerInfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 379
BrokerJoinFailureInfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 379Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 380
client_group_names . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 380event_type_names . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 380
Constructors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 380BrokerLockedClientQueueBrowser . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 380
Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 380deleteEvents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 380insertEventsAtHead . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 381insertEventsAtTail . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 381modifyEvents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 382
BrokerLockedForwardQueueBrowser . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 383Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 383
deleteEvents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 383insertEventsAtTail . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 384modifyEvents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 384
BrokerLockedQueueBrowser . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 385Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 385
deleteEvents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 385insertEventsAtHead . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 386insertEventsAtTail . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 386modifyEvents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 387
BrokerLogConfig . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 387Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 388Constructors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 388
BrokerLogConfig . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 388BrokerLogConfig . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 388
Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 389clearLogOutput . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 389clearLogOutputs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 389clearLogTopic . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 389clearLogTopics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 390getLogOutput . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 390getLogOutputs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 391getLogTopic . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 391getLogTopics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 391setLogOutput . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 392setLogOutput . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 392setLogTopic . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 393setLogTopic . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 393toString . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 394
webMethods Broker Administration Java API Programmer’s Guide Version 8.2 21
toString . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 394BrokerLogConfigEntry . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 394
Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 394code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 394enabled . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 394value . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 395
Constructors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 395BrokerLogConfigEntry . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 395BrokerLogConfigEntry . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 395
BrokerMonitorClient . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 395Constant . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 396Constructors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 396
BrokerMonitorClient . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 396BrokerMonitorClient . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 396
Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 397destroy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 397getHostName . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 397getPort . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 397getServerLogEntries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 397getServerLogStatus . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 398getServerRunStatus . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 399getServers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 399getVersion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 399getVersionNumber . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 400pruneMonitorLog . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 400reloadConfig . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 400reloadConfigForServer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 400startServer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 401toString . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 401
BrokerProcessInfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 401Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 401
data_directory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 401exectuable_name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 401
Constructors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 402BrokerProcessInfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 402BrokerProcessInfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 402
BrokerQueueBrowser . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 402Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 402
browseEvents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 402closeQueueBrowser . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 403getBrowserInfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 403getFilters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 403resetFilters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 404setFilter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 404setFilters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 404
22 webMethods Broker Administration Java API Programmer’s Guide Version 8.2
setPosition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 405BrokerQueueBrowserInfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 405
Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 405clientId . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 405browserId . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 405browserSessionId . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 406locked . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 406createTime . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 406
Constructors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 406BrokerQueueBrowserInfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 406BrokerQueueBrowserInfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 406
BrokerServerClient . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 406Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 407Constructors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 407
BrokerServerClient . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 407Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 408
createBroker . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 408destroy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 408getActivePort . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 409getActiveProcessInfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 409getActiveSSLConfig . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 409getActiveSSLConfigV2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 410getActiveSSLIdentity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 410getBasicAuthIdentity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 411getBasicAuthStatus . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 411getSavedSSLidentity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 412getAdminACL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 412getBrokers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 412getDefaultBrokerName . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 413getDescription . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 413getDNsFromCertFile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 413getFIPSMode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 414getHostName . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 415getLicense . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 415getLicenseContent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 415getLogConfig . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 416getPublicationProcessingState . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 416getRootDNsFromCertFile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 416getDNFromKeyStore . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 417getIssuerDNFromKeystore . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 418getRootDNsFromTrustStore . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 418getSavedSSLConfig . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 418getSavedSSLConfigV2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 419getSavedSSLIdentity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 419getServerLogEntries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 420
webMethods Broker Administration Java API Programmer’s Guide Version 8.2 23
getServerLogStatus . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 421getServerProcessRunStatus . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 421getServerProcessRunStatus . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 422getServerVersionNumber . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 423getSSLStatus . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 423getStats . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 423getUsageStats . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 425getVersion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 427pruneServerLog . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 427registerConnectionCallback . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 428resumePublishProcessing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 428setAdminACL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 429setBasicAuthIdentity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 429setDefaultBrokerName . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 430setDescription . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 430setLicense . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 431setLicenseContent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 431setLicenseFile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 432setLogConfig . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 432setSSLConfig . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 433setSSLConfig . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 434setSSLConfig . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 435startServerProcess . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 436startServerProcess . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 436stopProcess . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 437toString . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 438
BrokerServerConnectionCallback . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 438Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 438
handleHostConnectionChange . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 438BrokerServerLogEntry . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 439
Constants . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 439Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 439
entry_msg_id . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 439entry_msg_text . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 439entry_type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 439time_stamp . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 440
Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 440toString . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 440
BrokerServerLogInfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 440Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 440
first_entry . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 440last_entry . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 440num_entries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 440
BrokerSetFailureInfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 440Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 441
24 webMethods Broker Administration Java API Programmer’s Guide Version 8.2
client_group_names_to_destroy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 441client_group_names_to_modify . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 441event_type_names_to_destroy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 441event_type_names_to_modify . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 441failure_type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 441
Constructor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 441BrokerSetFailureInfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 441
BrokerSharedEventTypeInfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 441Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 442
accept_publish . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 442accept_subscribe . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 442event_type_name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 442is_synchronized . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 442subscribe_filter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 442
Constructors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 442BrokerSharedEventTypeInfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 442BrokerSharedEventTypeInfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 443
Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 443toString . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 443
BrokerSharedEventTypeRefuseUpdateInfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 443Constructor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 443
BrokerSharedEventTypeRefuseUpdateInfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 443BrokerSSLCertificate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 444
Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 444begin_date . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 444distinguished_name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 444end_date . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 444issuer_distinguished_name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 445serial_number . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 445status . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 445
Constructors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 445BrokerSSLCertificate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 445BrokerSSLCertificate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 445
BrokerSSLConfig . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 446Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 446
certificate_file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 446distinguished_name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 446issuer_distinguished_name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 446password . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 446
Constructors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 446BrokerSSLConfig . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 446BrokerSSLConfig . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 447
BrokerSSLConfigV2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 447Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 447
CRLType . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 447
webMethods Broker Administration Java API Programmer’s Guide Version 8.2 25
KeystoreType . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 447TruststoreType . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 447SSLProtocol . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 447
Constructors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 448BrokerSSLConfigV2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 448BrokerSSLConfigV2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 448
Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 448getCipherSuites . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 448setCipherSuites . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 448getCRL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 448setCRL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 448getCRLType . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 448setCRLType . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 449getKeystore . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 449setKeystore . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 449getKeystorePassword . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 449setKeystorePassword . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 449getKeystoreType . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 449setKeystoreType . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 449getSslProtocol . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 450setSslProtocol . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 450getTruststore . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 450setTruststore . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 450getTruststoreType . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 450setTruststoreType . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 451setTruststoreType . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 451getVerifyDepth . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 451setVerifyDepth . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 451toString . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 451
BrokerSSLIdentity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 451Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 452
getDN . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 452getIssuerDN . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 452
BrokerSSLStatus . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 452Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 452
error_string . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 452level . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 452status . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 452
Constructors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 453BrokerSSLStatus . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 453BrokerSSLStatus . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 453
BrokerTerritoryGatewayInfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 453Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 454
accessible_territories . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 454auth_type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 454
26 webMethods Broker Administration Java API Programmer’s Guide Version 8.2
encrypt_level . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 454gateway_broker_name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 454gateway_host_name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 454is_complete . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 454is_local . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 454is_primary_gateway . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 454remote_broker_description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 455remote_broker_name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 455remote_host_name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 455remote_territory_name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 455
Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 455toString . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 455toString . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 455
BrokerTerritoryInfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 456Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 456
auth_type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 456encrypt_level . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 456isLocalPublish . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 456territory_name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 456
Constructor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 456BrokerTerritoryInfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 456
Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 457toString . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 457toString . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 457
BrokerTraceEvent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 457Constants . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 457Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 458
app_name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 458broker_host . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 458broker_name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 458client_group . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 459client_id . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 459dest_client_id . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 459encrypt_level . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 459event_id . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 459event_type_name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 460has_tag . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 460ip_address . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 460is_authenticated . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 460key . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 460other_string . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 460recv_client_id . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 460seqn . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 461session_count . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 461session_id . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 461
webMethods Broker Administration Java API Programmer’s Guide Version 8.2 27
tag . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 461track_id . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 461
Constructor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 461BrokerTraceEvent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 461
Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 462toString . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 462
A. API Exceptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 463
28 webMethods Broker Administration Java API Programmer’s Guide Version 8.2
About this Guide
The webMethods Broker Administration Java API Programmer’s Guide describes the application programming interfaces (API) that you use to create event-based applications, using the Java language, which perform administrative functions.
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 concepts and specific knowledge of the Java programming language. In addition, you should be familiar with the webMethods Broker systems concepts, administration, and the webMethods Broker APIs.
This book assumes you are familiar with the terminology and basic operations of your operating system. If you are not, see the applicable documentation for that operating system.
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 (...).
webMethods Broker Administration Java API Programmer’s Guide Version 8.2 29
About this Guide
Documentation Installation
You can download the product documentation using the Software AG Installer. Depending on the release of the webMethods product suite, the location of the downloaded documentation will be as shown in the table below.
Online Information
You can find additional information about Software AG products at the locations listed below.
Note: The Empower Product Support Web site and the Software AG Documentation Web site replace Software AG ServLine24 and webMethods Advantage.
For webMethods... The documentation is downloaded to...
6.x The installation directory of each product.
7.x A central directory named _documentation in the main installation directory (webMethods by default).
8.x A central directory named _documentation in the main installation directory (Software AG by default).
If you want to... Go to...
Access the latest version of product documentation.
Software AG Documentation Web site
http://documentation.softwareag.com
30 webMethods Broker Administration Java API Programmer’s Guide Version 8.2
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...
webMethods Broker Administration Java API Programmer’s Guide Version 8.2 31
About this Guide
32 webMethods Broker Administration Java API Programmer’s Guide Version 8.2
1 Managing Broker Event Types
Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34
Understanding the BrokerAdminTypeDef . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34
Listing Event Type Definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35
Getting Event Type Statistics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37
Creating and Modifying Event Type Definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37
Destroying Event Type Definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39
Event Type Infosets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40
Destroying Infosets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40
webMethods Broker Administration Java API Programmer’s Guide Version 8.2 33
1 Managing Broker Event Types
Overview
This chapter describes how you can use the BrokerAdminClient interface, introduced in “Managing Broker Clients” on page 59, to obtain information about event types defined for a Broker. Reading this chapter should help you understand:
Listing event types defined for a particular Broker.
Listing all Broker clients which have subscriptions for an event type.
Obtaining event type statistics.
Creating or destroying an event type definition or event type infoset.
Getting or setting a event type's properties, including event fields and their types.
Note: For more information on event types and their features, see the webMethods Broker Client Java API Programmer’s Guide.
Understanding the BrokerAdminTypeDef
Many of the BrokerAdminClient methods described in this chapter use BrokerAdminTypeDef objects as a parameter or a returned value. The BrokerTypeDef class, described in the webMethods Broker Client Java API Programmer’s Guide, provides your client application with a read-only description of an event type definition. In contrast, the BrokerAdminTypeDef class allows your client application to both query and modify the properties of an event type definition.
Note: Unlike BrokerTypeDef objects, BrokerAdminTypeDef objects are not cached and are not affected if the client application's type definition cache is flushed.
BrokerAdminTypeDef objects are also used to represent the fields within an event definition. The following table shows the methods offered by the BrokerAdminTypeDef class.
Method Description
clearField
clearFields
Clears one or all fields in the type definition.
renameField Renames a field within a BrokerAdminTypeDef object.
clearModificationFlag
hasBeenModified
setModificationFlag
Manages the modification flag, which is used to track changes made to the event type definition.
getBaseTypeName Returns the event type name, without any event scope qualifier.
getScopeTypeName Returns the event type's scope name.
34 webMethods Broker Administration Java API Programmer’s Guide Version 8.2
1 Managing Broker Event Types
Listing Event Type Definitions
The BrokerClient.getEventTypeNames method, described in the webMethods Broker Client Java API Programmer’s Guide, can be used to return all the event type names defined for a Broker. Once you know the name of an event, you can use the BrokerAdminClient.getEventAdminTypeDef method to obtain an event type's definition. Your client must have permission to obtain this information.
The following example illustrates how to get an event type definition:
. . . String event_names[]; BrokerAdminTypeDef def; BrokerAdminClient c; try {
/* Create a Broker admin client */ c = new BrokerAdminClient(broker_host, broker_name, null,
getTypeName Returns the event type's fully-qualified name.
setTypeName Sets the fully-qualified name for the event type.
getDescription
setDescription
Manages the description for the event type.
getFieldDef
setFieldDef
Given a field name, obtains or sets the field's definition.
getFieldNames Returns the names of the fields within an event or structure field.
getFieldType
setFieldType
Manages the data type of an event field's value.
getStorageType
setStorageType
Manages the event's storage type property.
getTimeToLive
setTimeToLive
Manages the event's time-to-live property, which determines how long an event type will be available after being published before it expires and is destroyed.
insertFieldDef Adds a field to an event type or a structure field.
isSystemDefined Returns true if the event type is a system-defined type that may not be altered.
orderFields Manages the order of the fields in an event type or structure field.
toString Returns a string containing the type definition administration object in a human-readable format.
Method Description
webMethods Broker Administration Java API Programmer’s Guide Version 8.2 35
1 Managing Broker Event Types
client_group, "My Broker Monitor",null); /* Get a list of all event type */ event_names = c.getEventTypeNames(); /* Get the event definition for the first event type */ def = c.getEventAdminTypeDef(event_names[0]); System.out.println(“Event “+event_names[0]+” time-to-live=”
def.getTimeToLive()+” seconds”); } catch (BrokerException ex) {
System.out.println("Error getting event type definition\n"+ex); return;
} . . .
Getting Multiple Event Type Definitions
The following example illustrates how you can use the BrokerAdminClient.getEventAdminTypeDefs method to obtain multiple event type definitions in one method invocation.
. . . int i; String event_names[]; BrokerAdminTypeDef defs[]; BrokerAdminClient c; try {
/* Create a Broker admin client */ c = new BrokerAdminClient(broker_host, broker_name, null,
client_group, "My Broker Monitor",null); /* Get a list of all event types */ event_names = c.getEventTypeNames(); /* Get the event definition for each event type */ defs = c.getEventAdminTypeDefs(event_names); for(i = 0; i < defs.length; i++) {
/* Print the event def name and time-to-live value. */ System.out.println(“Event “+event_names[i]+” time-to-live=”
defs[i].getTimeToLive()+” seconds”+”\n”); }
} catch (BrokerException ex) { System.out.println("Error getting event type definitions\n"+ex); return;
} . . .
Getting Event Type Definitions by Scope
The BrokerAdminClient.getEventAdminTypeDefsByScope method allows your client application to obtain all the event type definitions belonging to a particular event scope in a single method invocation.
36 webMethods Broker Administration Java API Programmer’s Guide Version 8.2
1 Managing Broker Event Types
Getting Event Type Statistics
The BrokerAdminClient.getEventTypeStats method lets your client application obtain statistics for a particular event type definition. The statistics are returned as fields within a BrokerEvent.
After you have obtained the BrokerEvent containing the statistics, you can retrieve each field using the BrokerEvent.get<type>Field method, described in the webMethods Broker Client Java API Programmer’s Guide. The version of the get<type>Field method to be used will depend on the data type of field you are retrieving. The following example illustrates how to obtain a BrokerEvent containing an event type definition's statistics and extract the value of two fields.
. . . BrokerDate create_time; BrokerDate update_time; BrokerEvent e; BrokerAdminClient c; try {
/* Create a Broker admin client */ c = new BrokerAdminClient(broker_host, broker_name, null,
client_group, "My Broker Monitor",null);
/* Get the BrokerEvent containing an event type’s statistics */ e = c.getEventTypeStats(“myEventType”); /* Get the time and date the event type definition was created */ create_time = e.getDateField( “createTime”); /* Get the time and date the event type definition was modified */ update_time = e.getDateField( “updateTime”);
} catch (BrokerException ex) { System.out.println("Error getting event type statistics\n"+ex); return;
} . . .
Creating and Modifying Event Type Definitions
Your client application can use the BrokerAdminClient.setEventAdminTypeDef method to modify an event type's definition. Your application must first obtain and modify (or create and initialize) the desired BrokerAdminTypeDef object and provide it as a parameter to this method.
If the event type represented by the BrokerAdminTypeDef object does not exist on the Broker, it will be created. If the event type already exists on the Broker, it will be updated.
The BrokerAdminClient.setEventTypesAndClientGroups method can also be used to set event types as well as client groups for a Broker.
webMethods Broker Administration Java API Programmer’s Guide Version 8.2 37
1 Managing Broker Event Types
Modifying Event Fields
You can use the BrokerAdminTypeDef.insertFieldDef method to insert a new event field in an administrative type definition.
The BrokerAdminTypeDef.orderFields method allows you to change the order of event fields within an administrative type definition.
The BrokerAdminTypeDef.clearField method and the BrokerAdminTypeDef.clearFields method allow you to remove one or more event fields from an administrative type definition.
The BrokerAdminTypeDef.renameField method allows you to rename an event field within an administrative type definition.
You can use the BrokerAdminTypeDef.setFieldDef method to set the definition of an event field in an administrative type definition. If the specified field does not exist, it will be created.
The BrokerAdminTypeDef.setFieldType method allows you to set the data type of an event field in an administrative type definition. If the specified field does not exist, it will be created.
The following example illustrates how to create or modify an event type definition:
. . . BrokerAdminTypeDef def; BrokerAdminTypeDef field1, field2; BrokerAdminClient c; try {
/* Create a Broker admin client */ c = new BrokerAdminClient(broker_host, broker_name, null,
client_group, "My Broker Monitor",null);
/* Create the BrokerAdminTypeDef object for the event type */ def = new BrokerAdminTypeDef(“myEventType”,
BrokerTypeDef.FIELD_TYPE_EVENT);
/* Set two fields in the event type definition */ field1 = new BrokerAdminTypeDef(BrokerTypeDef.FIELD_TYPE_STRING); field2 = new BrokerAdminTypeDef(BrokerTypeDef.FIELD_TYPE_BOOLEAN);
/* Add the fields to the event type definition */ def.setFieldDef(“Name”, field1); def.setFieldDef(“Active”, field2);
/* Set the event type definition. * Note that if it doesn’t exist, it will be created. * If the event type definition does exist, it will be * replaced with the new version. */
c.setEventAdminTypeDef(def); } catch (BrokerException ex) {
System.out.println("Error creating/modifying event type def\n"+ex); return;
} . . .
38 webMethods Broker Administration Java API Programmer’s Guide Version 8.2
1 Managing Broker Event Types
Creating or Modifying Multiple Event Type Definitions
The BrokerAdminClient.setEventAdminTypeDefs method allows your client application to modify or create several event type definitions in a single method invocation. Your application must first obtain and modify (or create and initialize) the desired BrokerAdminTypeDef objects and provide them as input to this method. If any of the BrokerAdminTypeDef objects you provide do not exist on the Broker, they will be created. If any of the event type definitions already exist on the Broker, they will be updated
Destroying Event Type Definitions
You can use the BrokerAdminClient.destroyEventType method to destroy an event type definition on the Broker to which your BrokerAdminClient is connected. If an existing Broker client subscription or client group uses the event type, a BrokerDependencyException exception will be thrown and the event type will not be destroyed.
You can use the following methods to determine which Broker clients or client groups are dependent on a particular event type:
BrokerAdminClient.getClientIdsWhichAreSubscribed
BrokerAdminClient.getClientGroupsWhichCanPublish
BrokerAdminClient.getClientGroupsWhichCanSubscribe
The following example illustrates how to use the destroyEventType to destroy an event type definition:
. . . BrokerAdminClient c; try {
/* Create a Broker admin client */ c = new BrokerAdminClient(broker_host, broker_name, null,
client_group, "My Broker Monitor",null); /* Destroy the event type definition using the force option */ c.destroyEventType(“myEventType”, true);
} catch (BrokerException ex) { System.out.println("Error getting destroying event type\n"+ex); return;
} . . .
Destroying Multiple Event Types
The BrokerAdminClient.destroyEventTypes method allows your client application to destroy several event type definitions in a single method invocation. You must supply the names of the event types you wish to destroy and an indication of whether to force the destroy operation if there are Broker clients currently using any of the event types.
webMethods Broker Administration Java API Programmer’s Guide Version 8.2 39
1 Managing Broker Event Types
Event Type Infosets
The following BrokerClient methods, which are described in the webMethods Broker Client Java API Programmer’s Guide, allow you to retrieve event type infosets and infoset names:
The BrokerClient.getEventTypeInfoset method can be used to retrieve a specific infoset for a particular event type.
The BrokerClient.getEventTypeInfosets method can be used to retrieve all the infosets for a particular event type.
The BrokerClient.getEventTypeInfosetNames method can be used to retrieve all the infoset names for a particular event type.
Setting Event Type Infosets
Your client application can use the BrokerAdminClient.setEventTypeInfoset method to modify an event type's infoset. Your application must first obtain and modify (or create and initialize) a BrokerEvent object that represents the infoset and provide it as a parameter to this method, along with the event type name and infoset name. If your infoset name already exists for the event type name you specify, it will be updated. If it does not exist, it will be created.
Note: For information on event type name and infoset name restrictions, see the webMethods Broker Client Java API Programmer’s Guide.
Creating or Modifying Multiple Infosets
The BrokerAdminClient.setEventTypeInfosets method allows your client application to create or modify several infosets for a single event type definition in a one method invocation. You must supply an array of BrokerEvent objects that represent the infosets and the target event type name.
The name of each infoset will be taken from each BrokerEvent object's type name. If any of the infoset names already exist for the event type name you specify, they will be updated. If any of the infoset names do not exist, they will be created.
Destroying Infosets
You can use the BrokerAdminClient.destroyEventTypeInfoset method to destroy an infoset for an event type on the Broker to which your BrokerAdminClient is connected. You must supply the name of the event type and the name of the infoset you wish to destroy.
The following example illustrates how to use the destroyEventTypeInfoset method to destroy an infoset for an event type:
40 webMethods Broker Administration Java API Programmer’s Guide Version 8.2
1 Managing Broker Event Types
. . . BrokerAdminClient c; try {
/* Create a Broker admin client */ c = new BrokerAdminClient(broker_host, broker_name, null,
client_group, "My ",null); /* Destroy an infoset for an event type definition */ c.destroyEventTypeInfoset(“myEventType”, “myInfoset”);
} catch (BrokerException ex) { System.out.println("Error getting destroying infoset\n"+ex); return;
} . . .
Destroying Multiple Infosets
The BrokerAdminClient.destroyEventTypeInfosets method allows your client application to destroy several infosets for a single event type in a single method invocation. You must supply the name of the event type and the names of the infosets you wish to destroy.
webMethods Broker Administration Java API Programmer’s Guide Version 8.2 41
1 Managing Broker Event Types
42 webMethods Broker Administration Java API Programmer’s Guide Version 8.2
2 Getting Started
Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44
Overview of the webMethods Broker Administration API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44
Using the Administration API for Java . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47
webMethods Broker Java API Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48
webMethods Broker Administration Java API Programmer’s Guide Version 8.2 43
2 Getting Started
Overview
This chapter describes the basic features of the administration API for the webMethods Broker system. The API lets you create applications that automate the monitoring and management of your Information Brokers and Broker clients. You can also create applications that integrate your webMethods Brokers and Broker clients with existing network management systems.
After reading this chapter, you will be ready to learn how to use the webMethods Broker administration interfaces in your client applications.
Overview of the webMethods Broker Administration API
The webMethods Broker administration API allows your client applications to control and monitor the basic elements of the webMethods Broker system, including Broker Servers and the hosts on which they are running, Broker clients, client groups, event type definitions, SSL configurations, and tracing and logging functions. The following figure shows the elements that comprise a webMethods Broker system and their relationship to one another. For a complete list of attributes of Brokers, clients, client groups, and event types, see the webMethods Broker Client Java API Programmer’s Guide and Administering webMethods Broker.
44 webMethods Broker Administration Java API Programmer’s Guide Version 8.2
2 Getting Started
Elements of a webMethods Broker system
BrokerServerClient
The BrokerServerClient class, described in Chapter 3, “Managing Brokers and Broker Servers”, allows your client application to administer the Broker Server on which one or more Brokers are running. The administration methods offered by this interface allow your client application to:
Start and stop a Broker Server.
Create and destroy a Broker.
webMethods Broker Administration Java API Programmer’s Guide Version 8.2 45
2 Getting Started
List all of the Brokers running within a particular Broker Server.
Obtain statistics for the host where a Broker Server is running.
Pause all publishing clients on a Broker Server.
Chapter 3, “Managing Brokers and Broker Servers” describes the use of this class to administer hosts where Brokers are running.
BrokerAdminClient
The BrokerAdminClient interface allows your client application to administer a Broker. The methods offered by this interface allow your client application to:
List information for all of the Broker clients connected to the Broker.
List all of the client groups and event types defined for the Broker.
Create, modify, and destroy client groups and event type definitions.
Obtain statistics for a Broker client, client group, event type, or a Broker.
Chapter 4, “Managing Broker Clients” and “Managing Client Groups” on page 75 describe the use of this interface to administer Broker clients and client groups. Chapter 1, “Managing Broker Event Types” covers the methods offered for managing event types.
Monitoring Brokers
The webMethods Broker system provides a variety of ways for your client applications to monitor a Broker's activity. Chapter 10, “Monitoring Broker Activity” describes the interfaces and events available to your client application for monitoring Brokers.
Managing Security Configurations
The BrokerAccessControlList, BrokerServerClient , BrokerAdminClient, and BrokerSSLConfigV2 interfaces allow your client application to control the security configuration for Broker Servers and Brokers. Chapter 6, “Managing Security Configurations”covers the interfaces offered for managing SSL configurations.
Managing Territories
webMethods Broker allows two or more Brokers to cooperate as a territory. The use of territories allows an event published by a client connected to one Broker to be forwarded to a client connected to a different Broker within the same territory.
You may also configure two Brokers so that they form a gateway between two different territories.
46 webMethods Broker Administration Java API Programmer’s Guide Version 8.2
2 Getting Started
Chapter 7, “Managing Broker Territories” describes the interfaces you can use to configure and manage Broker territories.
Managing Clusters
webMethods Broker allows you to group two or more Brokers to form a cluster. The Brokers in a cluster share information about their event type definitions and client groups. The clusters can be configured with JMS load balancing policies for enabling client-side load balancing and failover. For more information, see the webMethods Messaging Programmer’s Guide.
You may also configure two Brokers so that they form a gateway between two different clusters.
Chapter 8, “Managing Broker Clusters” describes the interfaces you can use to configure and manage Broker clusters.
Managing Configurations
The webMethods Broker API for Java provides interfaces that allow you to load, store, import and export configuration information for Broker Servers, Brokers, Broker clients, client groups, and event types. These interfaces are described in Chapter 9, “Managing Site Configurations”.
Using the Administration API for Java
The webMethods Broker administration API is implemented as a Java package that provides all the necessary interfaces, classes and methods for creating administrative client applications.
Compatibility
This version of the webMethods Broker Java API, and applications developed with it, are compatible and fully inter-operable with Brokers and applications developed with the C, Java, and ActiveX APIs and webMethods 6.x and later.
Application Development with webMethods Broker
For information on application development, see the webMethods Broker Client Java API Programmer’s Guide.
webMethods Broker Administration Java API Programmer’s Guide Version 8.2 47
2 Getting Started
Application Deployment
When deploying your administrative client applications, you must also deploy the necessary webMethods Broker classes. The webMethods installation contains an archive with all of the files necessary for application deployment.
Note: These files must be in the application's CLASSPATH when the application is deployed.
The default location of the files required for application deployment are as follows:
webMethods Broker Java API 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.
The default location of the webMethods Broker Javadoc is as follows:
Platform Default 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
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
48 webMethods Broker Administration Java API Programmer’s Guide Version 8.2
3 Managing Brokers and Broker Servers
Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50
Understanding Broker Server Clients . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50
Managing a Broker Server Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52
Managing Brokers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55
webMethods Broker Administration Java API Programmer’s Guide Version 8.2 49
3 Managing Brokers and Broker Servers
Overview
This chapter describes how you can use the BrokerServerClient interface to manage the Messaging Brokers running in a particular Broker Server. Reading this chapter will help you understand:
Using a BrokerServerClient to list all the Brokers, including the default Broker, running in a Broker Server.
Using a BrokerServerClient to create and destroy a Broker.
How to create and destroy a BrokerServerClient object.
How to register callback methods for connection notification.
Using a BrokerServerClient to obtain usage statistics for a Broker Server.
Using a BrokerServerClient to get and set Broker Server properties, such as the default Broker name and the license string.
Understanding Broker Server Clients
A client program creates a BrokerServerClient object to manage a Broker Server's configuration and to control or monitor a Broker in that Broker Server.
For example, a network monitoring application might create a BrokerServerClient to learn how much swap space is available or the number of Brokers in a Broker Server. A network management application might use a BrokerServerClient to create a Broker on a particular host at 7AM in the morning and destroy it at 7PM at night.
Creating a BrokerServerClient
Creating a BrokerServerClient will establish a connection between your application and a Broker Server process on a particular host. Your application must specify the name of the host when creating the BrokerServerClient object.
The following example illustrates how to create a BrokerServerClient:
import COM.activesw.api.client.*; class myMonitor { static String broker_host = "localhost"; . . . public static void main(String args[]) { BrokerServerClient c; . . . /* Create a Broker Server client */ try { c = new BrokerServerClient(broker_host, null); } catch (BrokerException ex) { System.out.println("Error on create Broker Server client\n"+ex);
50 webMethods Broker Administration Java API Programmer’s Guide Version 8.2
3 Managing Brokers and Broker Servers
return; } . . .
Destroying a BrokerServerClient
The following example illustrates the use of the BrokerServerClient.destroy method, which disconnects the client from the host.
. . . BrokerServerClient c; . . . try {
c.destroy(); } catch (BrokerException ex) {
System.out.println("Error on Broker Server client destroy\n"+ex); return;
} . . .
Connection Notification
The connection notification feature allows you to register a callback method for a particular Broker Server client that will be invoked if the client is disconnected from the server.
Note: Connection callback methods do not have a global scope. They must be registered separately for each server client that wants to use this feature.
Defining a Callback Object
You use BrokerServerConnectionCallback to derive your own callback object. You must provide an implementation of the handleHostConnectionChange method to perform the processing you desire. You can implement this method to recreate any needed client state that may have been lost or to provide other functions, such as logging of error messages.
Registering the Callback Object
You use the BrokerServerClient.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.
webMethods Broker Administration Java API Programmer’s Guide Version 8.2 51
3 Managing Brokers and Broker Servers
When the BrokerServerConnectionCallback object's the callback method is invoked, that method's connect_state parameter will be set to one of the following BrokerClient-defined values shown in the following table.
Un-Registering Callback Objects
You can un-register a callback by invoking the BrokerServerClient.registerConnectionCallback method with a null callback object.
Managing a Broker Server Configuration
Getting Broker Server Statistics
You can use the BrokerServerClient.getStats method to obtain statistics for the Broker Server to which your BrokerServerClient is connected. The statistics are returned as fields within a BrokerEvent.
After you have obtained the BrokerEvent containing the statistics, you can retrieve each field using the appropriate BrokerEvent.get<type>Field method, as described in the webMethods Broker Client Java API Programmer’s Guide. The following example illustrates how to obtain and parse the BrokerEvent containing the Broker Server's statistics.
. . . int num_connections; boolean low_disk_space; BrokerEvent e; BrokerServerClient c; try {
/* Create a Broker Server client */ c = new BrokerServerClient(broker_host, null);
/* Get the BrokerEvent containing the Broker Server’s statistics */ e = c.getStats(); /* Get the total number of connections */ num_connections = e.getIntegerField( “numConnections”);
connect_state Meaning
CONNECT_STATE_CONNECTED The Client connection has been re-established, because automatic reconnect was enabled.
CONNECT_STATE_DISCONNECTED The client has been disconnected.
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.
52 webMethods Broker Administration Java API Programmer’s Guide Version 8.2
3 Managing Brokers and Broker Servers
/* Get the disk space status */ low_disk_space = e.getBooleanField( “isDiskSpaceLow”); . . .
} catch (BrokerException ex) { System.out.println("Error getting host statistics\n"+ex); return;
} . . .
Getting System Usage Statistics
The BrokerServerClient.getUsageStats method allows you to obtain system usage statistics for the host to which your BrokerServerClient is connected.
After you have obtained the BrokerEvent containing the statistics, you can retrieve each field using the BrokerEvent.get<type>Field method, described in the webMethods Broker Client Java API Programmer’s Guide. The version of the get<type>Field method to be used will depend on the data type of the field you are retrieving. The following example illustrates how to obtain a BrokerEvent containing the system usage statistics and extract the value of two fields.
. . . long swap_space_total; long swap_space_free; BrokerEvent e; BrokerServerClient c; try {
/* Create a Broker Server client */ c = new BrokerServerClient(broker_host, null);
/* Get the BrokerEvent containing the usage statistics */ e = c.getUsageStats(); /* Get the total amount of swap space */ swap_space_total = e.getLongField( “swapSpaceMax”); /* Get the swap space available */ swap_space_free = e.getLongField( “swapSpaceFree”); . . .
} catch (BrokerException ex) { System.out.println("Error getting usage statistics\n"+ex); return;
} . . .
Getting and Setting the Default Broker
You can use the BrokerServerClient.getDefaultBrokerName method to obtain the name of the default Broker on the Broker Server to which your BrokerServerClient is connected. If you do not specify a Broker name when you create a BrokerClient, as described in the webMethods Broker Client Java API Programmer’s Guide, your client will be connected to the default Broker.
You can use the BrokerServerClient.setDefaultBrokerName method to set the name of the default Broker.
webMethods Broker Administration Java API Programmer’s Guide Version 8.2 53
3 Managing Brokers and Broker Servers
The following example illustrates how to use the getDefaultBrokerName and setDefaultBrokerName methods to get and set the default Broker name.
. . . String broker_name; BrokerServerClient c; . . .
/* Create a Broker Server client */ c = new BrokerServerClient(broker_host, null); . . .
try { /* Get the default Broker name */ broker_name = c.getDefaultBrokerName();
} catch (BrokerException ex) { System.out.println("Error getting default Broker\n"+ex); return;
} try {
/* Set the default Broker name */ c.setDefaultBrokerName(“My Broker”); . . .
} catch (BrokerException ex) { System.out.println("Error setting default Broker\n"+ex); return;
} . . .
Getting and Setting Log Configuration
You can use the BrokerServerClient.getLogConfig method to obtain the logging configuration for a Broker Server and the BrokerLogConfig class represents logging configuration.
The BrokerServerClient.setLogConfig method allows you to set the logging configuration for a Broker Server.
Getting the Port Information
The BrokerServerClient.getActivePort method allows you to obtain the base port for the Broker Server to which your BrokerServerClient is connected. The base port is used for non-SSL connections and has a default value of 6849. The base port number is also used to calculate the port numbers as shown in the following table.
Port number Description
Base port number minus 1
Used for SSL connections without client authentication.
Base port number minus 2
Used for SSL connections with client authentication.
54 webMethods Broker Administration Java API Programmer’s Guide Version 8.2
3 Managing Brokers and Broker Servers
Getting and Setting the License
The BrokerServerClient.getLicense, and BrokerServerClient.getLicenseContent methods let you obtain the license details for the Broker Server to which your BrokerServerClient is connected.
The BrokerServerClient.setLicense, BrokerServerClient.setLicenseContent, and BrokerServerClient.setLicenseFile methods are used to set the license.
Note: For Broker Servers earlier than 8.0 version, the BrokerServerClient.getLicense method returns a string containing the Broker host's license.
Starting and Stopping the Host Process
You can use the BrokerServerClient.startServerProcess method to start the Broker Server process on the specified host. The stopProcess method is used to stop a Broker Server process.
The getServerProcessRunStatus method can be used to determine the state of the Broker Server process.
Managing Security Configurations
This topic is covered in Chapter 6, “Managing Security Configurations”.
Managing Brokers
The BrokerServerClient class provides several methods for monitoring and controlling Brokers. The BrokerAdminClient also offers a limited number of methods, described in “Broker Administration” on page 64, for monitoring a particular Broker.
Using Change Locks
If you have multiple client applications that want to manage a Broker, race conditions may result if more than one client attempts to update the Broker's configuration.
You can use the BrokerAdminClient.acquireChangeLock method to obtain a lock for the Broker to which a BrokerClient is connected. This method will return a BrokerChangeLock object with the variables shown in the following table.
Data Member Description
BrokerBoolean acquired; Set to 1 (true) if the lock was acquired by this BrokerClient, otherwise set to 0 (false).
webMethods Broker Administration Java API Programmer’s Guide Version 8.2 55
3 Managing Brokers and Broker Servers
Your client application should use the BrokerAdminClient.releaseChangeLock method to release a Broker change lock, after it has finished updating the Broker.
Listing all Brokers on a Host
The BrokerServerClient.getBrokers method lets you obtain a list of all the Brokers running in the Broker Server to which your BrokerServerClient is connected. An array of BrokerInfo objects is returned and each element contains details such as a Broker's name, description, and territory information. This method is available to all Broker Server clients.
The following example illustrates how to list all Brokers in a Broker Server:
. . . int i; BrokerInfo brokers[]; BrokerServerClient c; try {
/* Create a Broker Server client */ c = new BrokerServerClient(broker_host, null); /* Get a list of all Brokers in this server and print them out*/ brokers = c.getBrokers(); for(i = 0; i < brokers.length; i++) {
System.out.println(brokers[i].broker_name+”\n”); }
} catch (BrokerException ex) { System.out.println("Error getting Broker list\n"+ex); return;
} . . .
String client_id; If acquired is 0 (false), this member will contain the ID of the client currently holding a lock on the Broker. Otherwise, this member will be set to NULL. For information on client IDs, see “Broker Client Administration” on page 66.
int session_id; If acquired is 0 (false), this member will contain the session ID of the client currently holding a lock on the Broker. Otherwise, this member will be set to zero.
BrokerDate lock_time If acquired is 0 (false), this member will contain the date and time the lock was acquired. Otherwise, this member will be set to NULL.
Data Member Description
56 webMethods Broker Administration Java API Programmer’s Guide Version 8.2
3 Managing Brokers and Broker Servers
Creating and Destroying Brokers
You can use the BrokerServerClient.createBroker method to create a Broker in the Broker Server to which your BrokerServerClient is connected. You must supply the Broker's name and description. You may also specify that the Broker you are creating should be the default Broker. Your client must have administrative permission to with Broker Server.
The following example illustrates how to create a Broker:
. . . BrokerServerClient c; try {
/* Create a Broker Server client */ c = new BrokerServerClient(broker_host, null);
/* Create a Broker and make it the default */ c.createBroker( “My Broker”, “This is my Broker”, true); ...
} catch (BrokerException ex) { System.out.println("Error creating Broker\n"+ex); return;
} . . .
You can use the BrokerServerClient.destroy method to destroy a BrokerServerClient object. The BrokerServerClient will be disconnected from the Broker Server.
webMethods Broker Administration Java API Programmer’s Guide Version 8.2 57
3 Managing Brokers and Broker Servers
58 webMethods Broker Administration Java API Programmer’s Guide Version 8.2
4 Managing Broker Clients
Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60
Understanding BrokerAdminClients . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60
Broker Administration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64
Broker Client Administration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66
webMethods Broker Administration Java API Programmer’s Guide Version 8.2 59
4 Managing Broker Clients
Overview
This chapter describes how you can use the BrokerAdminClient interface to obtain information about Broker clients that are connected to a Broker. Reading this chapter should help you understand:
How to create and use a BrokerClient for administration purposes.
How to disconnect and reconnect an administrative BrokerClient.
How to obtain the identifiers of the Broker clients connected to a particular Broker.
How to obtain statistics for Broker clients connected to a Broker.
Getting or setting a Broker client's properties, including event subscriptions.
Destroying or disconnecting a Broker client.
Understanding BrokerAdminClients
The BrokerAdminClient class extends the BrokerClient class, described in the webMethods Broker Client Java API Programmer’s Guide. In addition to having access to all the BrokerClient methods, the BrokerAdminClient provides a wide array of methods for administering Information Brokers, Broker clients, client groups, and event type definitions. Your client program creates a BrokerAdminClient to monitor and control the operation of a particular Broker.
For example, a network monitoring application might create a BrokerAdminClient to:
Obtain usage statistics for a Broker, a particular Broker client, a client group, or an event type.
Obtain a list of a Broker's clients, client groups, and event type definitions.
Create or destroy a Broker client, client group, or event type definition.
Change the properties of a Broker client, client group, or event type definition.
This chapter focuses on administration methods related to Brokers and Broker clients. Chapter 5, “Managing Client Groups” describes the BrokerAdminClient methods for administering client groups and Chapter 1, “Managing Broker Event Types” describes the methods for administering event type definitions.
Creating a BrokerAdminClient
Creating a BrokerAdminClient will establish a connection between your application and a Broker. This connection is identified by the following tuple (an ordered set of values):
The name of the host where the Broker server is running.
The IP port number assigned to the Broker's server.
The name of the Broker.
60 webMethods Broker Administration Java API Programmer’s Guide Version 8.2
4 Managing Broker Clients
Multiple Broker clients within a single application that connect to the same Broker will all share a single network connection.
Your application creates an administrative Broker client by using the BrokerAdminClient constructor and specifying these parameters:
The name of the host where the Broker to which you want to connect is running.
The name of the Broker to which you wish to connect. You may 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. It can also be set or obtained using the BrokerServerClient class, described in Chapter 3, “Managing Brokers and Broker Servers”. See “Listing all Brokers on a Host” on page 56 for details on obtaining the names of Brokers available on a given host.
A unique client ID that identifies your Broker client. You may specify a null value if you wish 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, described in the webMethods Broker Client Java API Programmer’s Guide.
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. See Chapter 5, “Managing Client Groups” for information on using the BrokerAdminClient class to administer client groups.
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. For more information, see BrokerClientInfo.
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 the webMethods Broker Client Java API Programmer’s Guide.
The following example illustrates how to create a new BrokerAdminClient object. In this example, a null Broker name is passed to indicate that the caller wishes to connect to the default Broker on the host "localhost". A null client ID is specified, indicating that the Broker should generate a unique client ID. A client group named "admin" is requested and the application name is set to "My Broker Monitor." A null connection descriptor is passed, indicating that the caller wishes a default connection to be established.
import COM.activesw.api.client.*; class MyMonitor {
static String broker_host = "localhost"; static String broker_name = null; static String client_group = "admin"; . . . public static void main(String args[]) {
BrokerAdminClient c;
webMethods Broker Administration Java API Programmer’s Guide Version 8.2 61
4 Managing Broker Clients
. . . /* Create an administrative client */ try {
c = new BrokerAdminClient(broker_host, broker_name, null, client_group, "My Broker Monitor", null);
} catch (BrokerException ex) { System.out.println("Error creating admin client\n"+ex);
return; }
. . .
Destroying a BrokerAdminClient
The following example shows the use of the BrokerAdminClient.destroy method, which is inherited from the BrokerClient class described in the webMethods Broker Client Java API Programmer’s Guide. The client state and event queue for the BrokerAdminClient that is being destroyed will also be destroyed.
. . . BrokerAdminClient c; . . . try {
c.destroy(); } catch (BrokerException ex) {
System.out.println("Error destroying admin client\n"+ex); return;
} . . .
Using Multiple BrokerAdminClients
You may find that a number of programming situations are made easier by creating multiple BrokerAdminClient objects within a single application.
If your application needs to monitor several Brokers at once, you can use a separate client for each Broker.
Because different Broker clients can belong to distinct client groups, they can subscribe to and publish different event types and their administrative permissions may be different.
A multi-threaded application can spawn separate threads for each Broker client, which can result in a cleaner programming model.
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 will have been 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
62 webMethods Broker Administration Java API Programmer’s Guide Version 8.2
4 Managing Broker Clients
can continue retrieving events from the event queue. Disconnecting and reconnecting can be particularly useful for applications that wish to do batch-style processing at scheduled intervals.
Disconnecting a BrokerAdminClient
You can disconnect your BrokerAdminClient by calling the disconnect method inherited from the BrokerClient class. 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.
The following example illustrates how to disconnect a BrokerAdminClient:
. . . BrokerAdminClient c; . . . try {
c.disconnect(); } catch (BrokerException ex) {
System.out.println("Error disconnecting admin client\n"+ex); return;
} . . .
Reconnecting a BrokerAdminClient
You can reconnect a previously disconnected Broker client that has a life cycle of explicit-destroy by invoking the reconnectAdmin method and specifying the same client ID that was used when your client was last connected, as shown in the example below. The inherited BrokerClient.getClientId method is described in the webMethods Broker Client Java API Programmer’s Guide.
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 invocation of the disconnect method.
The following example illustrates how to reconnect a BrokerAdminClient:
static String broker_host = "localhost"; static String broker_name = null; static String client_group = "myExplicitDestroyClientGroup"; . . . public static void main(String args[]) {
BrokerAdminClient c; String client_id; . . . /* Create an admin client */ try {
c = new BrokerAdminClient(broker_host, broker_name, null, client_group, "My Broker Monitor",null);
} catch (BrokerException ex) {
webMethods Broker Administration Java API Programmer’s Guide Version 8.2 63
4 Managing Broker Clients
. . . } /* Save the client ID */ client_id = c.getClientId(); . . . /* Disconnect the admin client */ try {
c.disconnect(); } catch (BrokerException ex) {
. . . } . . . /* Reconnect the admin client with the same client_id */ try {
c.reconnectAdmin(broker_host, broker_name, client_id, null); } catch (BrokerException ex) {
. . . } . . .
Using the newOrReconnectAdmin Method
You might find it convenient to use the newOrReconnectAdmin method to create or reconnect an administrative client when your client application is expected to be executed repeatedly. The BrokerAdminClient.newOrReconnectAdmin method will attempt to create a new BrokerAdminClient. If the client already exists and was simply disconnected, it will be reconnected.
Broker Administration
The BrokerAdminClient provides a small set of methods for administering a particular instance of a Broker. See “Managing Brokers” on page 55 for information on the administration methods offered by the BrokerServerClient class.
Destroying a Broker
You can use the BrokerAdminClient.destroyBroker method to destroy the Broker to which your BrokerAdminClient is connected. Your client must have permission to destroy the Broker. Destroying the Broker will also destroy your BrokerAdminClient.
The following example illustrates how to destroy a Broker:
. . . BrokerAdminClient c; try {
/* Create a Broker Admin client */ c = new BrokerAdminClient(broker_host, broker_name, null,
“admin”, “My_Broker_Monitor”);
/* Destroy a Broker */ c.destroyBroker( “My_Broker”); ...
64 webMethods Broker Administration Java API Programmer’s Guide Version 8.2
4 Managing Broker Clients
} catch (BrokerException ex) { System.out.println("Error destroying Broker\n"+ex); return;
} . . .
Getting and Setting the Broker Description
You can obtain or set a Broker's description using the BrokerAdminClient.getBrokerDescription and BrokerAdminClient.setBrokerDescription methods.
Getting Broker Statistics
The BrokerAdminClient.getBrokerStats method allows you to obtain statistics for a Broker. The statistics are returned as fields within a BrokerEvent.
After you have obtained the BrokerEvent containing the statistics, you can retrieve each field using the BrokerEvent.get<type>Field method, described in the webMethods Broker Client Java API Programmer’s Guide. The version of the get<type>Field method to be used will depend on the data type of the field you are retrieving. The following example illustrates how to obtain a BrokerEvent containing the system usage statistics and extract the value of two fields.
. . . int num_clients; int num_event_types; BrokerDate create_date; BrokerEvent e; BrokerAdminClient c; try {
/* Create a Broker admin client */ c = new BrokerAdminClient(broker_host, broker_name, null,
client_group, "My Broker Monitor",null);
/* Get the BrokerEvent containing the Broker’s statistics */ e = c.getBrokerStats(); /* Get the time and date that the Broker was created */ create_date = e.getDateField( “createTime”); /* Get the number of connected clients */ num_clients = e.getIntegerField( “numClients”); /* Get the number of event type definitions */ num_event_types = e.getIntegerField( “numEventTypes”); . . .
} catch (BrokerException ex) { System.out.println("Error getting Broker statistics\n"+ex); return;
} . . .
webMethods Broker Administration Java API Programmer’s Guide Version 8.2 65
4 Managing Broker Clients
Broker Client Administration
Obtaining Broker Client Identifiers
The BrokerAdminClient.getClientIds method lets you obtain a list of all client identifiers known to the Broker to which your BrokerAdminClient is connected and to which your client has access.
The following example illustrates how to list all client identifiers for a Broker:
. . . int i; String client_ids[]; BrokerAdminClient c; try {
/* Create a Broker admin client */ c = new BrokerAdminClient(broker_host, broker_name, null,
client_group, "My Broker Monitor",null); /* Get a list of all client ids for this Broker and print them out*/ client_ids = c.getClientIds(); for(i = 0; i < client_ids.length; i++) {
System.out.println(client_ids[i]); }
} catch (BrokerException ex) { System.out.println("Error getting Client Id list\n"+ex); return;
} . . .
The BrokerAdminClient.getClientIdsByClientGroup method lets you obtain a list of all client identifiers belonging to the client group which you specify and to which your client has access. The following example illustrates how to list all client identifiers for a client group:
. . . int i; String client_ids[]; BrokerAdminClient c; try {
/* Create a Broker admin client */ c = new BrokerAdminClient(broker_host, broker_name, null,
client_group, "My Broker Monitor",null); /* List of all client ids for this client group and print them out*/ client_ids = c.getClientIdsByClientGroup(“myGroup”); for(i = 0; i < client_ids.length; i++) {
System.out.println(client_ids[i]); }
} catch (BrokerException ex) { System.out.println("Error getting Client Id list\n"+ex); return;
} . . .
66 webMethods Broker Administration Java API Programmer’s Guide Version 8.2
4 Managing Broker Clients
The BrokerAdminClient.getClientIdsWhichAreSubscribed method lets you obtain a list of all the client identifiers which have subscribed to a particular event type and to which your client has access. The following example illustrates how to list all client identifiers subscribed to an event type:
. . . int i; String client_ids[]; BrokerAdminClient c; try {
/* Create a Broker admin client */ c = new BrokerAdminClient(broker_host, broker_name, null,
client_group, "My Broker Monitor",null); /* Get a list of all client ids that are subscribed and print them out*/ client_ids = c.getClientIdsWhichAreSubscribed(“myEvent”); for(i = 0; i < client_ids.length; i++) {
System.out.println(client_ids[i]); }
} catch (BrokerException ex) { System.out.println("Error getting Client Id list\n"+ex); return;
} . . .
Getting Broker Client Information
You can use the BrokerAdminClient.getClientInfoById method to obtain a variety information about a particular Broker client, such as its state sharing limit and client group name. The information is returned as a BrokerClientInfo object, which contains the following Broker client information:
Application name.
State sharing status and limit.
Client group affiliation.
Highest publish sequence number.
All sessions for the Broker client.
A Broker client may share its client state, which means that several client applications can create BrokerClient objects using the same client identifier. All client application sessions using a particular client identifier will be described as an array of BrokerClientSession objects.
You can use the BrokerAdminClient.getClientInfosById method to obtain information about all Broker clients for a particular Broker.
The following example illustrates how to obtain BrokerClientInfo object and extract the value of three fields. In this example, the client identifier is hard-coded. See “Obtaining Broker Client Identifiers” on page 66 for information on discovering client identifiers at run time.
webMethods Broker Administration Java API Programmer’s Guide Version 8.2 67
4 Managing Broker Clients
. . . BrokerClientInfo inf; BrokerAdminClient c; try {
/* Create a Broker admin client */ c = new BrokerAdminClient(broker_host, broker_name, null,
client_group, "My Broker Monitor",null); /* Get the information for a particular Broker client */ inf = c.getClientInfoById(“A123”); System.out.println(“Application name: “+inf.app_name); System.out.println(“Can share state: “+inf.can_share_state); System.out.println(“Client group: “+inf.client_group); . . .
} catch (BrokerException ex) { System.out.println("Error BrokerClientInfo\n"+ex); return;
} . . .
Creating Broker Clients
You can use the create BrokerAdminClient.createClient method to create a Broker client on the Broker to which your BrokerAdminClient is connected. You must specify the following information:
A client identifier
A client group
An application name
You can also specify an optional connection description for the Broker client.
Because the resulting Broker client will have no connection to a client application, the life cycle of its client group must be explicit-destroy.
Reconnecting a Remote Broker
You can use the BrokerAdminClient.checkAndRestartForwarding method to restart remote Broker connections, where remote Brokers are territory and gateway Brokers. You can also specify to restart a connection to a specific remote Broker.
Disconnecting Broker Clients
You can use the BrokerAdminClient.disconnectClientById method to disconnect all Broker clients using a specific client identifier. 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.
68 webMethods Broker Administration Java API Programmer’s Guide Version 8.2
4 Managing Broker Clients
Note: If more than one client application is sharing the same client state, they are using the same client id and they will all be disconnected.
The following example illustrates how to disconnect a BrokerClient by client identifier. In this example, the client identifier is hard-coded. See “Obtaining Broker Client Identifiers” on page 66 for information on discovering client identifiers at run time.
. . . BrokerAdminClient c; try {
/* Create a Broker admin client */ c = new BrokerAdminClient(broker_host, broker_name, null,
client_group, "My Broker Monitor",null); /* Disconnect all Broker clients with a specific client identifier */ c.disconnectClientById(“A123”);
} catch (BrokerException ex) { System.out.println("Error disconnecting BrokerClient\n"+ex); return;
} . . .
Disconnecting by Session Identifier
A Broker client can share its client state, which means that several client applications can create BrokerClient objects using the same client identifier. In these cases, each client application's connection is represented by a BrokerClientSession object with a unique session identifier.
The following example shows how you can disconnect a single Broker client session by invoking the BrokerAdminClient.disconnectClientSessionById method.
. . . BrokerAdminClient c; BrokerClientInfo inf; int i; try {
/* Create a Broker admin client */ c = new BrokerAdminClient(broker_host, broker_name, null,
client_group, "My Broker Monitor",null); /* Get the information for a particular Broker client */ inf = c.getClientInfoById(“A123”); /* Get the session id of the client with an IP * address of 101.111.12.1 */ for( i = 0; i < inf.sessions.length; i++) {
if( inf.sessions[i].ip_address == 0x656f0c01) { /* Disconnect the Broker client by session identifier */ c.disconnectClientBySessionId(“A123”,
inf.sessions[i].session_id); }
} } catch (BrokerException ex) {
System.out.println("Error disconnecting BrokerClient by session\n" +ex);
webMethods Broker Administration Java API Programmer’s Guide Version 8.2 69
4 Managing Broker Clients
return; } . . .
Destroying Broker Clients
A specific Broker client may be destroyed by invoking the BrokerAdminClient.destroyClientById method.
The following example shows how to destroy a Broker client by ID:
. . . BrokerAdminClient c; try {
/* Create a Broker admin client */ c = new BrokerAdminClient(broker_host, broker_name, null,
client_group, "My Broker Monitor",null); /* Destroy a particular Broker client */ c.destroyClientById(“A123”); . . .
} catch (BrokerException ex) { System.out.println("Error destroying BrokerClient\n"+ex); return;
} . . .
Client State Sharing
The BrokerAdminClient.setClientStateShareLimitById method can be used to set the state sharing limit of a Broker client with a specific client identifier. webMethods Broker allows Broker clients in different applications to share the same client state. Sharing client state allows several Broker clients, possibly running 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.
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.
See the webMethods Broker Client Java API Programmer’s Guide for a thorough discussion of client state sharing.
Setting the Last-published Sequence Number
You can use the BrokerAdminClient.setClientLastPublishSequenceNumberById method to set the sequence number of the last event that the Broker client published. The Broker stores this sequence number and uses it to recognize and discard duplicate events which may be published by the Broker client.
70 webMethods Broker Administration Java API Programmer’s Guide Version 8.2
4 Managing Broker Clients
Clearing a Broker Client's Queue
The BrokerAdminClient.clearClientQueueById method can be used to clear the event queue of a Broker client with a specific client identifier. See “Obtaining Broker Client Identifiers” on page 66 for information on discovering client identifiers at run time.
Important! Use the BrokerAdminClient.clearClientQueueById 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, calling this method can have far-reaching effects.
You can use the BrokerAdminClient.getClientStatsById method to obtain information about a Broker client's queue, such as the current number of bytes and the number of events in the queue.
Tip! To clear the event queues of all Broker clients on a Broker Server, use BrokerServerClient.pruneServerLog method. For more information see, BrokerServerClient.
Broker Client Subscriptions
Listing Subscriptions
You can use the BrokerAdminClient.getClientSubscriptionsById method to get a list of all subscriptions registered for a Broker client with a specific client identifier. An array of BrokerSubscription objects is returned that represents all the Broker client's subscriptions. The BrokerSubscription class is described in the webMethods Broker Client Java API Programmer’s Guide.
Testing the Existence of a Subscription
The BrokerAdminClient.doesClientSubscriptionExistById method can be used to determine if a subscription exists for a particular Broker client. To use this method you must specify the client identifier and the event type name. You must also specify a subscription filter if the subscription that you wish to match was created with a filter. The method will return true if the subscription exists.
Creating Subscriptions
The BrokerAdminClient.createClientSubscriptionById method can be used to register a subscription for the Broker client with a specified client identifier. You provide the client identifier and a BrokerSubscription object that describes the event subscription to be registered.
The BrokerAdminClient.createClientSubscriptionsById method can be used to create several event subscriptions for a Broker client in one method invocation. You provide the client identifier and an array of BrokerSubscription objects that describe the event subscriptions to be registered.
webMethods Broker Administration Java API Programmer’s Guide Version 8.2 71
4 Managing Broker Clients
The BrokerSubscription class is described in the webMethods Broker Client Java API Programmer’s Guide.
Note: If any subscription specified by either of these methods has already been registered for the specified Broker client, the method will have no effect on that subscription.
Destroying Subscriptions
Use the BrokerAdminClient.destroyClientSubscriptionById method to destroy a subscription for the Broker client with a specified client identifier. You provide the client identifier and a BrokerSubscription object that describes the event subscription to be destroyed.
The BrokerAdminClient.destroyClientSubscriptionsById method can be used to destroy several event subscriptions for a Broker client in one method invocation. You provide the client identifier and an array of BrokerSubscription objects that describes the event subscriptions to be destroyed.
Getting Broker Client Statistics
The BrokerAdminClient.getClientStatsById method allows you to obtain statistics for a Broker client with a particular client identifier. The statistics are returned as fields within a BrokerEvent. You can retrieve each field using the BrokerEvent.get<type>Field method, described in the webMethods Broker Client Java API Programmer’s Guide. The version of the get<type>Field method to be used will depend on the data type of field you are retrieving.
The following example illustrates how to obtain the system usage statistics and extract the value of two fields. In this example, the client identifier is hard-coded. See “Obtaining Broker Client Identifiers” on page 66 for information on discovering client identifiers at run time.
. . . int events_published; int events_retrieved; BrokerEvent e; BrokerAdminClient c; try {
/* Create a Broker admin client */ c = new BrokerAdminClient(broker_host, broker_name, null,
client_group, "My Broker Monitor",null); /* Get the BrokerEvent containing a Broker clients stats */ e = c.getClientStatsById(“A123”); /* Get the number of events the Broker client has published */ events_published = e.getIntegerField( “numEventsPublished”); /* Get the number of events the Broker client has retrieved*/ events_retrieved = e.getIntegerField( “numEventsRetrieved”); . . .
} catch (BrokerException ex) { System.out.println("Error getting Broker statistics\n"+ex); return;
} . . .
72 webMethods Broker Administration Java API Programmer’s Guide Version 8.2
4 Managing Broker Clients
Getting Broker Client Infosets
The BrokerAdminClient.getClientInfosetById method allows you to obtain the infoset for a particular Broker client. The infoset is returned as Broker event for convenience.
You can use the BrokerAdminClient.setClientInfosetById method to set the infoset for a Broker client, given its client ID.
webMethods Broker Administration Java API Programmer’s Guide Version 8.2 73
4 Managing Broker Clients
74 webMethods Broker Administration Java API Programmer’s Guide Version 8.2
5 Managing Client Groups
Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76
Listing Client Groups . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76
Listing Client Identifiers by Group . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77
Getting Client Group Statistics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77
Creating and Destroying Client Groups . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78
BrokerClientGroupInfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80
Controlling Event Publications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80
Controlling Event Subscriptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81
Controlling Group Access . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82
webMethods Broker Administration Java API Programmer’s Guide Version 8.2 75
5 Managing Client Groups
Overview
This chapter describes how you can use the BrokerAdminClient interface to obtain information about client groups defined for a Broker. Reading this chapter should help you understand:
How to list client groups defined for a particular Broker.
How to list all Broker clients belonging to a client group.
How to obtain statistics for client groups defined for a Broker.
How to create or destroy a client group.
How to get or set a client group's properties, including event subscription and publication permissions.
Note: Chapter 4, “Managing Broker Clients” describes how to create, disconnect, reconnect and destroy a BrokerAdminClient object. For more information on client groups and their features, see webMethods Broker Client Java API Programmer’s Guide.
Listing Client Groups
The BrokerAdminClient.getClientGroupNames method lets you obtain a list of all client group names known to the Broker to which your BrokerAdminClient is connected. This method is available for use by any BrokerAdminClient.
The following example illustrates how to list all client group names for a Broker:
. . . int i; String client_groups[]; BrokerAdminClient c; try {
/* Create a Broker admin client */ c = new BrokerAdminClient(broker_host, broker_name, null,
client_group, "My Broker Monitor",null); /* List of all client groups for this Broker and print them out */ client_groups = c.getClientGroupNames(); for(i = 0; i < client_groups.length; i++) {
System.out.println(client_groups[i]); }
} catch (BrokerException ex) { System.out.println("Error getting client group names\n"+ex); return;
} . . .
76 webMethods Broker Administration Java API Programmer’s Guide Version 8.2
5 Managing Client Groups
Listing Client Identifiers by Group
The BrokerAdminClient.getClientIdsByClientGroup method lets you obtain a list of all client identifiers belonging to a particular client group.
The following example illustrates how to list client identifiers by client group:
. . . int i; String client_ids[]; BrokerAdminClient c; try {
/* Create a Broker admin client */ c = new BrokerAdminClient(broker_host, broker_name, null,
client_group, "My Broker Monitor",null); /* Get a list of all client IDs for a client and print them out */ client_ids = c.getClientIdsByClientGroup(“myGroup”); for(i = 0; i < client_ids.length; i++) {
System.out.println(client_ids[i]+”\n”); }
} catch (BrokerException ex) { System.out.println("Error getting client IDs by group\n"+ex); return;
} . . .
Getting Client Group Statistics
The BrokerAdminClient.getClientGroupStats method lets you obtain statistics for a client group. The statistics are returned as fields within a BrokerEvent.
After you have obtained the BrokerEvent containing the statistics, you can retrieve each field using the BrokerEvent.get<type>Field method, described in the webMethods Broker Client Java API Programmer’s Guide. The version of the get<type>Field method to be used will depend on the data type of field you are retrieving. The following example illustrates how to obtain a BrokerEvent containing a client group's statistics and how to extract the value of two fields.
. . . int events_published; BrokerDate create_time; BrokerEvent e; BrokerAdminClient c; try {
/* Create a Broker admin client */ c = new BrokerAdminClient(broker_host, broker_name, null,
client_group, "My Broker Monitor",null);
/* Get the BrokerEvent containing the client group statistics */ e = c.getClientGroupStats(“myGroup”); /* Get the time and date that the client group was created */ create_time = e.getDateField( “createTime”); /* Get the number of events publish by all clients in this group */ events_published = e.getIntegerField( “numEventsPublished”);
webMethods Broker Administration Java API Programmer’s Guide Version 8.2 77
5 Managing Client Groups
. . . } catch (BrokerException ex) {
System.out.println("Error getting client group statistics\n"+ex); return;
} . . .
Creating and Destroying Client Groups
You can use the BrokerAdminClient.createClientGroup method to create a client group for the Broker to which your BrokerAdminClient is connected. When creating a client group, you must specify the following:
The Broker client group's name. For information on client group name restrictions, see the webMethods Broker Client Java API Programmer’s Guide.
The life cycle of the Broker client belonging to the group; see “Life Cycle” on page 78.
The queue storage type for the Broker clients belonging to this group; see “Storage Type” on page 79.
The following example illustrates how you can create a client group using the BrokerAdminClient class.
. . . BrokerAdminClient c; try {
/* Create a Broker admin client */ c = new BrokerAdminClient(broker_host, broker_name, null,
client_group, "My Broker Monitor",null); /* Create a client group */ c.createClientGroup(“myGroup”,
BrokerAdminClient.LIFECYCLE_DESTROY_ON_DISCONNECT, BrokerTypeDef.STORAGE_GUARANTEED);
} catch (BrokerException ex) { System.out.println("Error creating client group\n"+ex); return;
} . . .
The BrokerAdminClient.setEventTypesAndClientGroups method can also be used to set event types as well as client groups for a Broker.
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 a Broker client belonging to that group. The life cycle is specified as one of the BrokerAdminClient.LIFECYCLE_* values shown in the following table.
78 webMethods Broker Administration Java API Programmer’s Guide Version 8.2
5 Managing Client Groups
Storage Type
The queue storage type associated with your Broker client's client group will determine the storage reliability of the events that are queued for a Broker client belonging to the group. The storage type is specified as one of the BrokerTypeDef.STORAGE_* values shown below.
Setting Client Group Descriptions
You can use the BrokerAdminClient.setClientGroupDescription method to set the description for a particular client group. You must supply the client group's name and the new description and your client must have permission to change the client group's information.
Note: For information on client group name restrictions, see the webMethods Broker Client Java API Programmer’s Guide.
Destroying Client Groups
The BrokerAdminClient.destroyClientGroup method allows your applications to destroy a client group defined for a particular Broker. If any existing Broker clients belong to the group, a BrokerDependencyException exception will be thrown and the client group will not be destroyed.
Value Description
LIFECYCLE_DESTROY_ON_DISCONNECT The Broker will destroy the client state whenever the connection between a Broker client and the Broker is lost.
LIFECYCLE_EXPLICIT_DESTROY The client state will be maintained if the Broker client is disconnected. Used for client applications that need to maintain state in the event of network or system failures.
Life Cycle Description
STORAGE_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.
STORAGE_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.
webMethods Broker Administration Java API Programmer’s Guide Version 8.2 79
5 Managing Client Groups
You can use the BrokerAdminClient.getClientIdsByClientGroup method to obtain a list of any Broker clients currently belonging to a group.
The following example illustrates how to destroy a client group for a Broker:
. . . BrokerAdminClient c; try {
/* Create a Broker admin client */ c = new BrokerAdminClient(broker_host, broker_name, null,
client_group, "My Broker Monitor",null); /* Destroy a client group and any current clients, too. */ c.destroyClientGroup(“myGroup”, true);
} catch (BrokerException ex) { System.out.println("Error destroying client group\n"+ex); return;
} . . .
BrokerClientGroupInfo
You can use the BrokerAdminClient.getClientGroupInfo method to obtain a BrokerClientGroupInfo object for a client group. The BrokerClientGroupInfo method contains the following client group information:
Group name
Group description
Life cycle
Storage type
The BrokerAdminClient.getClientGroupInfos method allows you to obtain BrokerClientGroupInfo objects for more than one client group.
Controlling Event Publications
The BrokerAdminClient.getClientGroupCanPublishList method lets you obtain all of the event types that may be published or delivered by Broker clients belonging to a particular client group.
The following example illustrates how to get a client group's can-publish list:
. . . int i; String publish_events[]; BrokerAdminClient c; try {
/* Create a Broker admin client */ c = new BrokerAdminClient(broker_host, broker_name, null,
client_group, "My Broker Monitor",null); /* Get event types that may be published by clients in this group.*/ publish_events = c.getClientGroupCanPublishList(“myGroup”);
80 webMethods Broker Administration Java API Programmer’s Guide Version 8.2
5 Managing Client Groups
for(i = 0; i < publish_events.length; i++) { System.out.println(publish_events[i]);
} } catch (BrokerException ex) {
System.out.println("Error getting can-publish list\n"+ex); return;
} . . .
Use the BrokerAdminClient.setClientGroupCanPublishList method to set the list of event types to which Broker clients belonging to a particular client group may subscribe.
The BrokerAdminClient.getClientGroupsWhichCanPublish method lets you obtain the names of all the client groups that can publish a particular event type.
The following example illustrates how to get client groups that can publish an event type:
int i; String groups[]; BrokerAdminClient c; try {
/* Create a Broker admin client */ c = new BrokerAdminClient(broker_host, broker_name, null,
client_group, "My Broker Monitor",null); /* Get a list of all client groups that may publish a * particular event type. */ groups = c.getClientGroupsWhichCanPublish(“myEventType”); for(i = 0; i < groups.length; i++) {
System.out.println(groups[i]); }
} catch (BrokerException ex) { System.out.println("Error getting client groups\n"+ex); return;
} . . .
Controlling Event Subscriptions
The BrokerAdminClient.getClientGroupCanSubscribeList method lets you obtain all of the event types to which Broker clients belonging to a particular client group my subscribe or receive as a delivered event.
The following example illustrates how to get a client group's can-subscribe list:
. . . int i; String subscribe_events[]; BrokerAdminClient c; try {
/* Create a Broker admin client */ c = new BrokerAdminClient(broker_host, broker_name, null,
client_group, "My Broker Monitor",null); /* Get event types to which Broker clients in * this client group may subscribe. */
webMethods Broker Administration Java API Programmer’s Guide Version 8.2 81
5 Managing Client Groups
subscribe_events = c.getClientGroupCanSubscribeList(“myGroup”); for(i = 0; i < subscribe_events.length; i++) {
System.out.println(subscribe_events[i]); }
} catch (BrokerException ex) { System.out.println("Error gettingcan-subscribe list\n"+ex); return;
} . . .
Use the BrokerAdminClient.setClientGroupCanSubscribeList method to set the list of event types to which Broker clients belonging to a particular client group may subscribe.
The BrokerAdminClient.getClientGroupsWhichCanSubscribe method lets you obtain the names of all the client groups that may subscribe to a particular event type or receive a delivered event of that type.
The following example illustrates how to get client groups that can subscribe to an event type:
. . . int i; String groups[]; BrokerAdminClient c; try {
/* Create a Broker admin client */ c = new BrokerAdminClient(broker_host, broker_name, null,
client_group, "My Broker Monitor",null); /* Get a list of all client groups that may subscribe to * particular event type. */ groups = c.getClientGroupsWhichCanPublish(“myEventType”); for(i = 0; i < groups.length; i++) {
System.out.println(groups[i]); }
} catch (BrokerException ex) { System.out.println("Error getting client groups\n"+ex); return;
} . . .
Controlling Group Access
For information on controlling security configurations, see Chapter 6, “Managing Security Configurations”.
82 webMethods Broker Administration Java API Programmer’s Guide Version 8.2
6 Managing Security Configurations
Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84
Access Control Lists . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84
Broker Server Security Configurations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86
Client Group Security Configurations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87
Territory Security Configurations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88
Territory Gateway Security Configurations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89
Cluster Security Configurations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89
Cluster Gateway Security Configurations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90
webMethods Broker Administration Java API Programmer’s Guide Version 8.2 83
6 Managing Security Configurations
Overview
This chapter describes how your administrative client applications can use the Java interfaces to obtain information about and configure the security settings for a Broker Server, Broker, or client group.
Access Control Lists
The BrokerAccessControlList class is used to control the entities that may access a resource. A Broker Server can use an access control list (ACL) to determine which Broker clients are allowed administrative access. A client group may use an ACL to control who may create or reconnect a Broker client that is associated with the group.
A BrokerAccessControlList object actually contains two lists:
User list
For basic authentication, a list of basic authentication user names.
For SSL authentication, a list of DNs of entities that are allowed access to the resource.
Authenticator list
For basic authentication, a list of basic authentication aliases.
For SSL authentication, a list of DNs of certificate authorities that are trusted. These trusted authorities should be signers of the certificates associated with the user DNs.
An entity that wishes to access a resource associated with a BrokerAccessControlList must provide the credentials. Access is granted as follows:
If both the user lists and authenticator lists are empty, access is granted.
If the user list is not empty, the basic authentication user name or the entity's DN must be in the list.
If the authenticator list is not empty, then the basic authentication alias or the entity's authenticator DN must be in the list.
If both user lists and authenticator lists are not empty,
For basic authentication, the basic authentication user name must be on the user list and the basic authentication alias must be on the authenticator list.
For SSL authentication, the entity's DN must be on the user list and its authenticator DN must be on the authenticator list.
84 webMethods Broker Administration Java API Programmer’s Guide Version 8.2
6 Managing Security Configurations
Getting and Setting Authenticator Names
The BrokerAccessControlList class offers methods for obtaining and setting the basic authentication aliases or the SSL DNs of trusted certificate authorities. An entity that wishes to access the resource associated with this BrokerAccessControlList object must provide the required credentials.
You can use the BrokerAccessControlList.getAuthNames method to obtain the names of all the basic authentication aliases or SSL certificate authenticators.
You can use the BrokerAccessControlList.getAuthNameState method to determine if a particular basic authentication alias or the SSL certificate authority's DN is defined in the list.
The BrokerAccessControlList.setAuthNames method can be used to set all the basic authentication aliases or SSL DNs of trusted certificate authorities.
You can use the BrokerAccessControlList.setAuthNameState method to add or remove a basic authenticator alias or SSL trusted certificate authority DN. You must provide basic authenticator alias or SSL DN and a boolean indicator signifying whether or not the name is allowed.
The BrokerAccessControlList.setAuthNameStates method allows you to add or remove several basic authenticator aliases or SSL DNs with a single method invocation.
Getting and Setting Names
The BrokerAccessControlList class offers methods for obtaining and setting the user lists. This lists represent the entities that are allowed access to the resource associated with this BrokerAccessControlList object.
You can use the BrokerAccessControlList.getUserNames method to obtain all the basic authentication user names or SSL user names.
The BrokerAccessControlList.getUserNameState method can be used to determine if the specifies user is currently in the list.
The BrokerAccessControlList.setUserNames method can be used to set all the basic authentication user names or SSL user names.
You can use the BrokerAccessControlList.setUserNameState method to add or remove a basic authentication user or SSL user . You must provide a user name and a boolean indicator signifying whether or not the name is allowed.
The BrokerAccessControlList.setUserNameStates method allows you to add or remove several basic authentication users or SSL users with a single method invocation.
webMethods Broker Administration Java API Programmer’s Guide Version 8.2 85
6 Managing Security Configurations
Converting to a String
There are two BrokerAccessControlList.toString methods that allow you to convert a the contents of an ACL to a string. One allows you to specify the number of 4-character spaces that are used for indentation.
Broker Server Security Configurations
A Broker Server's security configuration is used to control the Broker Server's identity, which is how the Broker Server is authenticated by the Broker clients that connect to them. The security configuration with which a Broker Server was started is called its active configuration. An administrative client application may change a Broker Server's saved security configuration, but that configuration will not take effect until the next time the Broker Server is started. A Broker Server's active and saved configurations may be identical or they may be different, depending on whether or not the configuration has been changed since the Broker Server was started.
The BrokerConnectionDescriptor class contains the basic authentication user name and password information.
The BrokerSSLConfigV2 class contains the following SSL information:
The names of the Broker Server's keystore and trust store files, and the password for accessing the keystore.
The trusted root of the certificate authority that issued the Broker Server's certificate.
The type of the SSL CRL file used by the SSL configuration and the path to the CRL file.
See Administering webMethods Broker for complete information on the use of keystore files, trust store files, and the information needed to configure SSL.
Important! The BrokerSSLConfigV2 class only works with Broker Server version 7.1 and above; the related class, BrokerSSLConfig, only works with Broker Servers of version 6.5.2 and below.
Retrieving and Setting Broker Server Security Configurations
The following methods return the Broker Server's Identity:
BrokerServerClient.getBasicAuthStatus returns true if basic authentication is configured on the Broker Server.
BrokerServerClient.getSavedSSLidentity returns the Broker Server's basic authentication identity that is in use.
BrokerServerClient.getActiveSSLIdentity and BrokerServerClient.getSavedSSLidentity return a BrokerSSLIdentity object
86 webMethods Broker Administration Java API Programmer’s Guide Version 8.2
6 Managing Security Configurations
BrokerSSLIdentity.getDN returns the Broker Server's SSL DN
BrokerSSLIdentity.getIssuerDN returns the SSL authenticator DN for the Broker Server's SSL certificate.
BrokerServerClient.getDNFromKeyStore and BrokerServerClient.getRootDNsFromTrustStore methods returns the SSL keystore and trust store information.
BrokerServerClient.getSSLStatus returns the Broker Server's SSL status. The BrokerSSLStatus class describes whether SSL is enabled, disabled, not supported, or if there is an error in the configuration.
Retrieving and Setting Broker Server ACLs
The BrokerServerClient.getAdminACL method allows you to obtain a Broker Server's ACL. This list represents the user names or the authenticator names of all the entities that may issue administrative requests using a BrokerServerClient object.
You can use the BrokerServerClient.getDNsFromCertFile method to obtain all of the DNs from a Broker Server's certificate file.
You can use the BrokerServerClient.getRootDNsFromCertFile method to obtain all of the issuer DNs from a Broker Server's certificate file.
The BrokerServerClient.setAdminACL method allows you to set the ACL for a Broker Server.
Client Group Security Configurations
Client groups can use the BrokerAccessControlList class to determine which entities are allowed to create a BrokerClient or BrokerAdminClient object that belongs to the group.
You can use the BrokerAdminClient.getClientGroupACL method to obtain the ACL for a particular client group. You must supply the name of the client group whose ACL you wish to obtain.
The BrokerAdminClient.setClientGroupACL method allows you to set the ACL for a particular client group.
Obtaining Security Information for Client Sessions
You can determine which Broker client sessions are using basic authentication or SSL by following these steps:
1 Use the BrokerAdminClient.getClientInfoById or getClientInfosById method to obtain a BrokerClientInfo object for the particular Broker client in which you are interested.
2 Examine each BrokerClientSession object contained in the BrokerClientInfo.sessions data member.
webMethods Broker Administration Java API Programmer’s Guide Version 8.2 87
6 Managing Security Configurations
3 Examine the BrokerClientSession.encrypt_level and encrypt_version data members to determine if SSL is being used. If SSL authentication is being used without encryption, then these data members will not be set. Note that BrokerClientSession.encrypt_level is deprecated.
4 Examine the BrokerClientSession.ssl_certificate data member to determine the Broker client's DN. While a Broker must always authenticate itself to a Broker client, the client is not required to authenticate itself to Broker. This data member will not be set under those circumstances.
Territory Security Configurations
Setting Territory Security
The BrokerAdminClient.setTerritorySecurity method allows you to set the level of security and the type of authentication that is to be used in the territory. All Brokers in the territory must be properly configured for the new settings and the changes may take some time to be propagated throughout the territory.
When using this method, you must provide the type of authentication to be used, specified as one of the BrokerAdminClient.AUTH_TYPE_* values.
Important! Use this method with care because changing the security setting might cause the territory to become partially disconnected. For example, setting SSL authentication or encryption when one or more Brokers are not configured for SSL will cause the territory to become partially disconnected.
Territory ACLs
Brokers in a territory can use the BrokerAccessControlList class to authenticate Brokers that want to join the territory. ACLs are only checked when a Broker joins the territory.
You can use the BrokerAdminClient.getTerritoryACL method to obtain the ACL for the Broker's territory.
You can use the BrokerAdminClient.setTerritoryACL method to configure the ACL for the Broker's territory.
88 webMethods Broker Administration Java API Programmer’s Guide Version 8.2
6 Managing Security Configurations
Territory Gateway Security Configurations
Setting Territory Security
The BrokerAdminClient.setTerritoryGatewaySecurity method allows you to set the level of security and the type of authentication that is to be used in a territory gateway. Each of the two Brokers that make up the gateway must be properly configured for the new settings.
When using this method, you must provide the following parameters:
The territory name.
The type of authentication to be used, specified as one of the BrokerAdminClient.AUTH_TYPE_* values.
For information on territory gateway security, see Administering webMethods Broker.
Important! Use this method with care because changing the security setting might cause the gateway to become disconnected. For example, setting SSL authentication or encryption when the remote Broker is not configured for SSL will cause the gateway to become disconnected.
Territory Gateway ACLs
Brokers that make up a territory gateway can use the BrokerAccessControlList class to authenticate the remote Broker that makes up the other half of the gateway. ACLs are only checked when a Broker opens a connection to the other Broker in the gateway.
You can use the BrokerAdminClient.setTerritoryGatewayACL method to configure the ACL for the territory gateway, and the BrokerAdminClient.getTerritoryGatewayACL method to obtain the ACL information for the gateway. In both cases, a BrokerException will be thrown if basic authentication or SSL is not enabled.
Cluster Security Configurations
Setting Cluster Security
The BrokerAdminClient.setClusterSecurity method allows you to set the level of security and the type of authentication that is to be used in the cluster. All Brokers in the cluster must be properly configured for the new settings and the changes may take some time to be propagated throughout the cluster.
When using this method, you must provide the following parameters:
webMethods Broker Administration Java API Programmer’s Guide Version 8.2 89
6 Managing Security Configurations
The type of authentication to be used, specified as one of the BrokerAdminClient.AUTH_TYPE_* values.
Important! Use this method with care because changing the security setting might cause the cluster to become partially disconnected. For example, setting SSL authentication or encryption when one or more Brokers are not configured for SSL will cause the cluster to become partially disconnected.
Cluster ACLs
Brokers in a cluster can use the BrokerAccessControlList class to authenticate Brokers that want to join the cluster. ACLs are only checked when a Broker joins the cluster.
You can use the BrokerAdminClient.getClusterACL method to obtain the ACL for the Broker's cluster.
You can use the BrokerAdminClient.setClusterACL method to configure the ACL for the Broker's cluster.
Cluster Gateway Security Configurations
Setting Cluster Security
The BrokerAdminClient.setClusterGatewaySecurity method allows you to set the level of security and the type of authentication that is to be used in a cluster gateway. Each of the two Brokers that make up the gateway must be properly configured for the new settings.
When using this method, you must provide the following parameters:
The cluster name
The Broker name
The type of authentication to be used, specified as one of the BrokerAdminClient.AUTH_TYPE_* values
For information on cluster gateway security, see Administering webMethods Broker.
Important! Use this method with care because changing the security setting might cause the gateway to become disconnected. For example, setting SSL authentication or encryption when the remote Broker is not configured for SSL will cause the gateway to become disconnected.
90 webMethods Broker Administration Java API Programmer’s Guide Version 8.2
6 Managing Security Configurations
Cluster Gateway ACLs
Brokers that make up a cluster gateway can use the BrokerAccessControlList class to authenticate the remote Broker that makes up the other half of the gateway. ACLs are only checked when a Broker opens a connection to the other Broker in the gateway.
You can use the BrokerAdminClient.setClusterGatewayACL method to configure the ACL for the cluster gateway, and the BrokerAdminClient.getClusterGatewayACL method to obtain the ACL information for the gateway. In both cases, a BrokerException will be thrown if basic authentication or SSL is not enabled.
webMethods Broker Administration Java API Programmer’s Guide Version 8.2 91
6 Managing Security Configurations
92 webMethods Broker Administration Java API Programmer’s Guide Version 8.2
7 Managing Broker Territories
Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94
Using Territories . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94
Using Territory Gateways . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97
webMethods Broker Administration Java API Programmer’s Guide Version 8.2 93
7 Managing Broker Territories
Overview
This chapter describes how your administrative client applications can create and manage Broker-to-Broker communication through territories and territory gateways.
Using Territories
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 figure below 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.
Note: A Broker can be a member of no more than one territory. However, territories can be linked together using territory gateways. For more information, see “Using Territory Gateways” on page 97.
Broker-to-Broker communication
To share information and forward events, Brokers must join a territory. A Broker can only belong to one territory and 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.
Creating a New Territory
The BrokerAdminClient.createTerritory method allows you to create a new territory. You must provide the name of the territory to be created.
94 webMethods Broker Administration Java API Programmer’s Guide Version 8.2
7 Managing Broker Territories
Note: For information on territory name restrictions, see the webMethods Broker Client Java API Programmer’s Guide.
When the new territory is created, the Broker to which the administrative client is connected will become the first member of that territory.
Adding a Broker to an Existing Territory
You can use the BrokerAdminClient.joinTerritory method to add a Broker to an existing territory. You must provide the following arguments to this method:
The name of the remote Broker whose territory this Broker is to join.
The name of the Broker host where the remote Broker is running.
The Broker to which the administrative client is connected will be added to the remote Broker's territory.
Removing a Broker from a Territory
The BrokerAdminClient.leaveTerritory method lets you remove the Broker to which your BrokerAdminClient is connected from its territory. When a Broker leaves a territory, communication must take place between the Broker being removed and the other Brokers in the territory.
You must provide the following arguments to this method:
The number of milliseconds to wait for the operation to complete. You can specify -1 to indicate you do not wish the operation to be subject to a time-out.
An indication of whether or not the operation should be forced to complete, even if communication with the other Brokers in the territory exceeds the time limit.
You can use the BrokerAdminClient.removeBrokerFromTerritory method to remove a Broker from a territory. This function will not wait for the communication between the other Brokers in the territory to complete, but returns as soon as the removal process is initiated.
You must provide the following arguments to this method:
The name of the Broker to be removed from the territory.
The name of the Broker host where the Broker is executing.
Getting Territory Information
You can use the BrokerAdminClient.getTerritoryInfo method to obtain territory information for the Broker to which your Broker client is connected. A BrokerTerritoryInfo object is returned that contains the territory name, Broker host, Broker name, and Broker description for your Broker. An exception will be thrown if the Broker is not a member of a territory.
webMethods Broker Administration Java API Programmer’s Guide Version 8.2 95
7 Managing Broker Territories
Listing Brokers in a Territory
The BrokerAdminClient.getBrokersInTerritory method allows you to obtain information about all the other Brokers in the territory to which the Broker client's Broker belongs.
The array of BrokerInfo objects returned are used to contain the territory name, Broker host, Broker name, and Broker description for a particular Broker.
Obtaining Territory Statistics
You can use the BrokerAdminClient.getTerritoryStats method to obtain statistics about the territory to which the Broker client's Broker belongs. These statistics include information about the other Brokers in the territory as well as information about the number of events that have been enqueued, forwarded, and received.
The statistics are returned as a BrokerEvent, for convenience. See getTerritoryStats on page 255 for a complete list of the territory statistics that are available.
Maintaining a Connection Between Brokers in a Territory
In network configurations where territory Brokers are separated by a firewall, the firewall may terminate a connection if the connection remains idle for a long period of time. To prevent this from occurring, you can use the BrokerAdminClient.setRemoteBrokerKeepAlive method. This method causes a remote Broker to periodically issue "keep-alive" messages to another Broker in its territory, preventing the connection between them from remaining idle too long.
Activating the Keep-Alive Feature between Territory Brokers
To activate the keep-alive feature between two Brokers in a territory, you use the BrokerAdminClient.setRemoteBrokerKeepAlive method and specify the following two parameters:
broker_name. The name of the Broker to which you want the remote Broker to issue keep-alive messages.
KeepAlive. The number of seconds between the keep-alive messages. To disable gateway the keep-alive feature, specify 0 seconds.
Be aware that BrokerAdminClient.setTerritoryGatewayKeepAlive method activates the keep-alive feature in one direction. That is, it instructs the Broker to which the BrokerAdminClient client is connected, to issue keep-alive messages to a second Broker in the territory. It does not instruct the second Broker to issue keep-alive messages. To activate the keep-alive feature in both directions, you must execute BrokerAdminClient.setRemoteBrokerKeepAlive on both Brokers.
To implement the keep-alive feature correctly, you must understand the conditions that cause the firewalls to drop a connection. Given this information, you can determine which Broker should issue keep-alive messages (it may be both) and the frequency at which the messages need to be issued to prevent the connection from dropping.
96 webMethods Broker Administration Java API Programmer’s Guide Version 8.2
7 Managing Broker Territories
Checking the Keep-Alive Settings for a Broker
To get the Broker's current keep-alive setting, you use the BrokerAdminClient.getRemoteBrokerKeepAlive method. This method returns the remote Broker's current keep-alive interval (in seconds) for a connection to another Broker in its territory.
Setting Territory Security
For information on territory security, see “Territory Security Configurations” on page 88.
Using Territory Gateways
Though the webMethods Broker systems restricts a Broker to membership in more than one territory at a time, you can configure a territory gateway to enable event forwarding between different territories. A Broker may act as a gateway to a single territory or to multiple territories.
The next figure shows a territory gateway between Broker_1 and Broker_2 that effectively joins the two territories. The territory gateway allows an event published by a client program connected to Broker_1, a member of territory A, to be forwarded through the territory gateway and be received by a client program connected to Broker_3, a member of territory B.
webMethods Broker Administration Java API Programmer’s Guide Version 8.2 97
7 Managing Broker Territories
Territory gateway communication
Creating and Destroying Gateways
The BrokerAdminClient.createTerritoryGateway method allows you to obtain information about all the other Brokers in the territory to which the Broker client's Broker belongs.
You must provide the following arguments to this method:
The name of the remote Broker that will act as the other endpoint of the gateway.
The name of the host where the remote Broker is running.
The name of the remote Broker's territory.
A territory gateway consists of two endpoints, so this function must be invoked for both endpoints before the gateway activation complete. Failure to activate both ends of the gateway will result in the gateway being in an incomplete state.
You can use the BrokerAdminClient.destroyTerritoryGateway method to destroy one endpoint of a territory gateway. You must provide the following arguments to this method:
Name of the Broker to which this gateway is connected in the specified territory.
98 webMethods Broker Administration Java API Programmer’s Guide Version 8.2
7 Managing Broker Territories
The name of the territory whose gateway is to be destroyed.
A territory gateway consists of two endpoints, so this function must be invoked for both endpoints before the gateway destruction is complete.
Setting Shared Event Types
The BrokerAdminClient.setTerritoryGatewaySharedEventTypes method can be used to set the event types that will be forwarded or received by a gateway Broker. You specify the following parameters:
The territory name.
An array of BrokerSharedEventTypeInfo objects.
Each BrokerSharedEventTypeInfo object contains:
The event type name.
An indication of whether or not this Broker will accept events of this type that are being published or delivered from the remote territory
An indication of whether or not this Broker will accept forwarded subscriptions or deliver events of this type to the remote territory.
An indication of whether or not this event type is synchronized with the remote territory.
Listing Local Gateways
The BrokerAdminClient.getLocalClusterGateways method lets you obtain information about all the gateways available from the current Broker. An array of BrokerTerritoryGatewayInfo objects are returned which describe the gateways.
Listing All Gateways
You can use the BrokerAdminClient.getAllClusterGateways method to obtain information about all the gateways available within your Broker's territory or through gateways accessible to your Broker. An array of BrokerTerritoryGatewayInfo objects are returned which describe the gateways.
Managing Event Types
The BrokerAdminClient.getTerritoryGatewaySharedEventTypes method lets you obtain information about all the event types that are shared between two territory gateway Brokers. You must provide the following arguments to the territory name whose shared event type information is to be returned. This method returns an array of BrokerSharedEventTypeInfo objects that describes all of the shared event types.
webMethods Broker Administration Java API Programmer’s Guide Version 8.2 99
7 Managing Broker Territories
The BrokerAdminClient.setTerritoryGatewaySharedEventTypes method allows you to set the complete list of shared event types for a territory gateway. The is_synchronized variable in each element of infos will be ignored.
Note: To configure gateway event type sharing, first save the can-subscribe settings on both sides of the gateway and then save the can-publish settings. It is important to set the can-subscribe settings before the can-publish settings and to set them in separate invocations of this function.
You can control the content of the events that are forwarded through the gateway by specifying a subscribe_filter. If event filtering by the gateway is not desired, the subscribe_filter member should be set to null. For more information of event filtering, see the webMethods Broker Client Java API Programmer’s Guide.
Note: When porting applications from an earlier release, be sure to set the subscribe filter to either a valid value or to NULL.
Obtaining Gateway Statistics
You can use the BrokerAdminClient.getTerritoryGatewayStats method to obtain statistics about a territory gateway. These statistics include information about the gateway Broker as well as information about the number of events that have been enqueued, forwarded, and received.
You must provide the name of the territory whose statistics are to be returned.
The statistics are returned as an event, for convenience. See getTerritoryGatewayStats on page 251 for a complete listing of the territory statistics that are available.
Maintaining a Connection Between Gateway Brokers
In network configurations where gateway Brokers are separated by a firewall, the firewall may terminate a connection if the connection remains idle for a long period of time. To prevent this from occurring between gateway Brokers, you can use the BrokerAdminClient.setTerritoryGatewayKeepAlive method. This method causes a gateway Broker to periodically issue "keep-alive" messages to the other Broker, preventing the connection between them from remaining idle too long.
Activating the Keep-Alive Feature between Gateway Brokers
To activate the keep-alive feature on a gateway Broker, you use the BrokerAdminClient.setTerritoryGatewayKeepAlive method and specify the following two parameters:
territory_name. The name of the territory where the remote gateway Broker resides.
KeepAlive. The number of seconds between the keep-alive messages. To disable gateway keep-alive feature, specify 0 seconds.
100 webMethods Broker Administration Java API Programmer’s Guide Version 8.2
7 Managing Broker Territories
Be aware that BrokerAdminClient.setTerritoryGatewayKeepAlive method activates the keep-alive feature in one direction. That is, it instructs the Broker to which the BrokerAdminClient client is connected, to issue keep-alive messages to the gateway Broker in the other territory. It does not instruct the remote gateway Broker to issue keep-alive messages. To activate keep-alive messages in both directions, you must execute BrokerAdminClient.setTerritoryGatewayKeepAlive on both gateway Brokers.
To implement the keep-alive feature correctly, you must understand the conditions that cause the firewalls to drop a connection. (In most cases, you will need to coordinate with the network administrators at each end of the gateway to obtain information about the behavior of the firewalls.) Given this information, you can determine which gateway Broker must issue keep-alive messages (it may be both) and the frequency at which the messages need to be issued to prevent the connection from dropping.
Checking the Keep-Alive Settings for a Gateway Broker
To get the gateway Broker's current keep-alive setting for a particular territory, you use the BrokerAdminClient.getTerritoryGatewayKeepAlive method. This method returns the gateway Broker's current keep-alive interval (in seconds) for a given territory.
Pausing a Gateway Broker
To temporarily halt forwarding of events from one gateway Broker to another, you use the BrokerAdminClient.setTerritoryGatewayPause method. When you use this method, you specify the territory whose events you want to hold and set the pause parameter to true.
Once you pause the forwarding of events to a particular territory, the gateway Broker queues documents for that territory in an event-forwarding queue. The Broker does not resume forwarding events to the remote territory until event-forwarding is explicitly re-enabled.
Pausing Traffic in Both Directions
Be aware that the BrokerAdminClient.setTerritoryGatewayPause method halts the flow of traffic in one direction. That is, it stops the Broker to which the BrokerAdminClient client is connected from sending outbound messages to a specified territory. It does not halt the flow of inbound traffic to the gateway Broker from the remote territory. To halt both inbound and outbound between two gateway Brokers, you must execute BrokerAdminClient.setTerritoryGatewayPause on both Brokers.
Note that once you pause the forwarding queue for a territory, it remains paused even if the gateway Broker is restarted or the Broker Admin client disconnects.
Pausing Traffic to and from Multiple Territories
If a Broker serves as a gateway to multiple territories, and you want to pause outbound traffic to all of the territories, execute BrokerAdminClient.setTerritoryGatewayPause on the gateway Broker once for each remote territory.
webMethods Broker Administration Java API Programmer’s Guide Version 8.2 101
7 Managing Broker Territories
Similarly, if you want to halt inbound traffic to a gateway Broker from multiple remote territories, execute BrokerAdminClient.setTerritoryGatewayPause on each remote gateway Broker.
Unpausing a Gateway Broker
To re-enable event forwarding, you re-execute BrokerAdminClient.setTerritoryGatewayPause and set the pause parameter to false.
Checking the Current Pause Setting
To check the state of event-forwarding queues on the gateway Broker, execute the BrokerAdminClient.getTerritoryStats method and examine the gateway_pause field in the Broker event that BrokerAdmin.getTerritoryStats returns.
Static Gateway Forwarding
The static gateway forwarding feature ensures consistent document flow across a gateway between two territories at all times. Documents defined by the gateway permissions list are allowed to flow over the gateway. Once static gateway forwarding is enabled, the documents are forwarded to the remote territory at all times, regardless of any client subscriptions on the remote territory.
Essentially, the static gateway forwarding feature force feeds documents to the remote territory. When there are no subscribers on the remote territory, forwarded documents will be dropped at the gateway peer of the remote territory. Disabling static gateway forwarding resumes the normal behavior of subscription based gateway forwarding.
Note: The static gateway forwarding feature is only supported on a webMethods Broker Version 6.1 Service Pack 4 and later. The Brokers on the other end of the gateway can be of any version. In addition, you cannot enable static gateway forwarding on a Broker that is either not in a territory or does not have a gateway to the specified remote territory.
To enable static gateway forwarding, use the BrokerAdminClient.setStaticGatewayForwarding method and set enable to true.
To check the status of the static gateway subscription set on a remote territory from the current Broker, execute the BrokerAdminClient.getStaticGatewayForwarding method.
For more information about static gateway forwarding, see Administering webMethods Broker.
Refusing Document Type Updates Across a Gateway
By default, changes made to shared document types on one side of a gateway are propagated to a Broker territory on the other side of the gateway. However, you can configure a territory to refuse updates made on the other side of a gateway. This setting provides the following security measures:
102 webMethods Broker Administration Java API Programmer’s Guide Version 8.2
7 Managing Broker Territories
Lockdown of a local territory. Unauthorized changes made in a neighboring territory are not carried over to the local territory.
Protection against accidental changes made to shared document types in the neighboring territory.
Configuring a territory to refuse updates is done at the local end of a gateway. If you want the Broker territories on both sides of a gateway to refuse updates, you must configure the setting from both sides.
Update Refusal Classes and Methods
You have the option of refusing all changes to document types made in the neighboring territory, or specifying which document types cannot be changed.
The following methods set and return whether a gateway refuses all updates made in a neighboring territory: BrokerAdminClient.setTerritoryGatewayRefuseAllUpdates and BrokerAdminClient.getTerritoryGatewayRefuseAllUpdates.
The following methods set and return the document types for which a gateway refuses updates: BrokerAdminClient.setTerritoryGatewayRefuseEventTypeUpdates and BrokerAdminClient.getTerritoryGatewayRefuseEventTypeUpdates.
The BrokerSharedEventTypeRefuseUpdateInfo class stores information about how a particular event type is shared across a territory gateway, and whether the event type itself or updates to the event type are refused.
If you configure both the BrokerAdminClient.setTerritoryGatewayRefuseAllUpdates and BrokerAdminClient.setTerritoryGatewayRefuseEventTypeUpdates methods, BrokerAdminClient.setTerritoryGatewayRefuseAllUpdates takes precedence, and updates to all shared document types are refused.
Synchronizing Updates
If you turned on an update refusal setting for the local territory and an update is made to a shared document type on the other side of the territory gateway, all document flow to the local territory stops. At this point, you need to synchronize the document types by using one of the methods described below:
For update refusals set on the local side of a gateway, deliver a document of the type that was refused to the remote side of the gateway.
Change the event type definition;
On the remote side of the gateway, revert the update back to the previous document type definition.
On the local side of the gateway, update the document type definition.
Turn off the update refusal flag.
After you synchronize the updates, document flow to the local territory will restart.
webMethods Broker Administration Java API Programmer’s Guide Version 8.2 103
7 Managing Broker Territories
Note: Broker Server issues alerts for event flow suspension and resumption.
Setting Territory Gateway Security
For information on territory gateway security, see “Territory Gateway Security Configurations” on page 89.
104 webMethods Broker Administration Java API Programmer’s Guide Version 8.2
8 Managing Broker Clusters
Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 106
Using Clusters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 106
Using Cluster Gateways . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109
webMethods Broker Administration Java API Programmer’s Guide Version 8.2 105
8 Managing Broker Clusters
Overview
This chapter describes how your administrative client applications can create and manage Broker-to-Broker communication through clusters and cluster gateways.
Using Clusters
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.
Note: A Broker may be a member of no more than one cluster. However, clusters can be linked together using cluster gateways. For more information, see “Using Cluster Gateways” on page 109.
To share information and forward events, Brokers must join a cluster. A Broker can only belong to one cluster and all Brokers within the same cluster have knowledge of one another's event type definitions and client groups. The Brokers in a cluster do not forward documents to other Brokers in the cluster. For more information on this feature, see Administering webMethods Broker.
Creating a New Cluster
The BrokerAdminClient.createCluster method allows you to create a new cluster. You must provide the name of the cluster to be created.
Note: For information on cluster name restrictions, see the webMethods Broker Client Java API Programmer’s Guide.
When the new cluster is created, the Broker to which the administrative client is connected will become the first member of that cluster.
Adding a Broker to an Existing Cluster
You can use the BrokerAdminClient.addBrokerToCluster method to add a Broker to an existing cluster. You must provide the following arguments to this method:
The name of the remote Broker whose cluster this Broker is to join
The name of the Broker host where the remote Broker is running
The Broker to which the administrative client is connected will be added to the remote Broker's cluster.
106 webMethods Broker Administration Java API Programmer’s Guide Version 8.2
8 Managing Broker Clusters
Removing a Broker from a Cluster
The BrokerAdminClient.leaveCluster method lets you remove the Broker to which your BrokerAdminClient is connected from its cluster. When a Broker leaves a cluster, communication must take place between the Broker being removed and the other Brokers in the cluster.
You must provide the following arguments to this method:
The number of milliseconds to wait for the operation to complete. You can specify -1 to indicate you do not wish the operation to be subject to a time-out.
An indication of whether or not the operation should be forced to complete, even if communication with the other Brokers in the cluster exceeds the time limit.
You can use the BrokerAdminClient.removeBrokerFromCluster method to remove a Broker from a cluster. This function will not wait for the communication between the other Brokers in the cluster to complete, but returns as soon as the removal process is initiated.
You must provide the following arguments to this method:
The name of the Broker to be removed from the cluster.
The name of the Broker host where the Broker is executing.
Getting Cluster Information
You can use the BrokerAdminClient.getClusterInfo method to obtain cluster information for the Broker to which your Broker client is connected. A BrokerClusterInfo object is returned that contains the cluster name, Broker host, Broker name, and Broker description for your Broker. An exception will be thrown if the Broker is not a member of a cluster.
Listing Brokers in a Cluster
The BrokerAdminClient.getBrokersInCluster method allows you to obtain information about all the other Brokers in the cluster to which the Broker client's Broker belongs.
The array of BrokerInfo objects returned are used to contain the cluster name, Broker host, Broker name, and Broker description for a particular Broker.
Obtaining Cluster Statistics
You can use the BrokerAdminClient.getClusterStats method to obtain statistics about the cluster to which the Broker client's Broker belongs. These statistics include information about the other Brokers in the cluster as well as information about the number of events that have been enqueued, forwarded, and received.
The statistics are returned as a BrokerEvent, for convenience. See getClusterStats for a complete listing of the cluster statistics that are available.
webMethods Broker Administration Java API Programmer’s Guide Version 8.2 107
8 Managing Broker Clusters
Maintaining a Connection Between Brokers in a Cluster
In network configurations where cluster Brokers are separated by a firewall, the firewall may terminate a connection if the connection remains idle for a long period of time. To prevent this from occurring, you can use the BrokerAdminClient.setRemoteBrokerKeepAlive method. This method causes a remote Broker to periodically issue "keep-alive" messages to another Broker in its cluster, preventing the connection between them from remaining idle for too long.
Activating the Keep-Alive Feature between Cluster Brokers
To activate the keep-alive feature between two Brokers in a cluster, you use the BrokerAdminClient.setRemoteBrokerKeepAlive method and specify the following two parameters:
broker_name. The name of the Broker to which you want the remote Broker to issue keep-alive messages.
KeepAlive. The number of seconds between the keep-alive messages. To disable gateway the keep-alive feature, specify 0 seconds.
Be aware that BrokerAdminClient.setClusterGatewayKeepAlive method activates the keep-alive feature in one direction. That is, it instructs the Broker to which the BrokerAdminClient client is connected, to issue keep-alive messages to a second Broker in the cluster. It does not instruct the second Broker to issue keep-alive messages. To activate the keep-alive feature in both directions, you must execute BrokerAdminClient.setRemoteBrokerKeepAlive on both Brokers.
To implement the keep-alive feature correctly, you must understand the conditions that cause the firewalls to drop a connection. Given this information, you can determine which Broker should issue keep-alive messages (it may be both) and the frequency at which the messages need to be issued to prevent the connection from dropping.
Checking the Keep-Alive Settings for a Broker
To get the Broker's current keep-alive setting, you use the BrokerAdminClient.getRemoteBrokerKeepAlive method. This method returns the remote Broker's current keep-alive interval (in seconds) for a connection to another Broker in its cluster.
Setting Cluster Security
For information on cluster security, see “Cluster Security Configurations” on page 89.
108 webMethods Broker Administration Java API Programmer’s Guide Version 8.2
8 Managing Broker Clusters
Using Cluster Gateways
Though the webMethods Broker systems restricts a Broker to membership in more than one cluster at a time, you can configure a cluster gateway to enable event forwarding between different clusters. A Broker may act as a gateway to a single cluster or to multiple clusters. One Broker can have multiple gateway connections to the Brokers in the other cluster. Multiple gateway connections is not possible in territories.
Creating and Destroying Cluster Gateways
The BrokerAdminClient.createClusterGateway method creates a cluster gateway to the specified cluster by having this Broker communicate with the remote Broker specified by broker_host and broker_name.
You must provide the following arguments to this method:
The name of the remote Broker's cluster
The name of the host where the remote Broker is running
The name of the remote Broker that will act as the other endpoint of the gateway
A cluster gateway consists of two endpoints, so this function must be invoked for both endpoints before the gateway activation is complete. Failure to activate both ends of the gateway will result in the gateway being in an incomplete state.
You can use the BrokerAdminClient.destroyClusterGateway method to destroy one endpoint of a cluster gateway. You must provide the following arguments to this method:
The name of the cluster whose gateway is to be destroyed
Name of the Broker to which this gateway is connected in the specified cluster
A cluster gateway consists of two endpoints, so this function must be invoked for both endpoints before the gateway destruction is complete.
Setting Shared Event Types
The BrokerAdminClient.setClusterGatewaySharedEventTypes method can be used to set the event types that will be forwarded or received by a gateway Broker. You specify the following parameters:
The cluster name
Broker name in the specified cluster
An array of BrokerSharedEventTypeInfo objects
Each BrokerSharedEventTypeInfo object contains:
The event type name
webMethods Broker Administration Java API Programmer’s Guide Version 8.2 109
8 Managing Broker Clusters
An indication of whether or not this Broker will accept events of this type that are being published or delivered from the remote cluster
An indication of whether or not this Broker will accept forwarded subscriptions or deliver events of this type to the remote cluster
An indication of whether or not this event type is synchronized with the remote cluster
Setting Primary Gateway
The BrokerAdminClient.setClusterPrimaryGateway method can be used to set the primary gateway to the cluster. You specify the following parameters:
The cluster name.
Broker name belonging to the specified cluster.
Note: Ensure that all the cluster gateway links between a pair of clusters are identical. The permissions such as the sharedEventTypeInfo and KeepAlive must be the same on all the gateway links. During gateway link failover, when the connection switches from the primary gateway connection to the next available gateway connection, the gateway connection setting must be same as the failed gateway link so that the switch over does not impact the runtime operations.
Listing Local Gateways
The BrokerAdminClient.getLocalClusterGateways method lets you obtain information about all the gateways available from the current Broker. An array of BrokerClusterGatewayInfo objects are returned which describe the gateways.
Listing All Gateways
You can use the BrokerAdminClient.getAllClusterGateways method to obtain information about all the gateways available within your Broker's cluster or through gateways accessible to your Broker. An array of BrokerClusterGatewayInfo objects are returned which describe the gateways.
Managing Event Types
The BrokerAdminClient.getClusterGatewaySharedEventTypes method lets you obtain information about all the event types that are shared between two cluster gateway Brokers. This method returns an array of BrokerSharedEventTypeInfo objects which describe all of the shared event types.
110 webMethods Broker Administration Java API Programmer’s Guide Version 8.2
8 Managing Broker Clusters
The BrokerAdminClient.setClusterGatewaySharedEventTypes method allows you to set the complete list of shared event types for a cluster gateway. The is_synchronized variable in each element of infos will be ignored.
Note: To configure gateway event type sharing, first save the can-subscribe settings on both sides of the gateway and then save the can-publish settings. It is important to set the can-subscribe settings before the can-publish settings and to set them in separate invocations of this function.
You can control the content of the events that are forwarded through the gateway by specifying a subscribe_filter. If event filtering by the gateway is not desired, the subscribe_filter member should be set to null. For more information of event filtering, see the webMethods Broker Client Java API Programmer’s Guide.
Note: When porting applications from an earlier release, be sure to set the subscribe filter to either a valid value or to NULL.
Obtaining Gateway Statistics
You can use the BrokerAdminClient.getClusterGatewayStats method to obtain statistics about a cluster gateway. These statistics include information about the gateway Broker as well as information about the number of events that have been enqueued, forwarded, and received. You must provide the name of the cluster and the name of the cluster gateway Broker.
The statistics are returned as an event, for convenience. See getClusterGatewayStats for a complete listing of the cluster statistics that are available.
Maintaining a Connection Between Gateway Brokers
In network configurations where gateway Brokers are separated by a firewall, the firewall may terminate a connection if the connection remains idle for a long period of time. To prevent this from occurring between gateway Brokers, you can use the BrokerAdminClient.setClusterGatewayKeepAlive method. This method causes a gateway Broker to periodically issue "keep-alive" messages to the other Broker, preventing the connection between them from remaining idle too long.
Activating the Keep-Alive Feature between Gateway Brokers
To activate the keep-alive feature on a gateway Broker, you use the BrokerAdminClient.setClusterGatewayKeepAlive method and specify the following three parameters:
cluster_name. The name of the cluster where the remote gateway Broker resides
Broker name. The name of the Broker belonging to the cluster specified by the cluster_name.
webMethods Broker Administration Java API Programmer’s Guide Version 8.2 111
8 Managing Broker Clusters
KeepAlive. The number of seconds between the keep-alive messages. To disable gateway keep-alive feature, specify 0 seconds.
Be aware that BrokerAdminClient.setClusterGatewayKeepAlive method activates the keep-alive feature in one direction. That is, it instructs the Broker to which the BrokerAdminClient client is connected, to issue keep-alive messages to the gateway Broker in the other cluster. It does not instruct the remote gateway Broker to issue keep-alive messages. To activate keep-alive messages in both directions, you must execute BrokerAdminClient.setClusterGatewayKeepAlive on both gateway Brokers.
To implement the keep-alive feature correctly, you must understand the conditions that cause the firewalls to drop a connection. (In most cases, you will need to coordinate with the network administrators at each end of the gateway to obtain information about the behavior of the firewalls.) Given this information, you can determine which gateway Broker must issue keep-alive messages (it may be both) and the frequency at which the messages need to be issued to prevent the connection from dropping.
Checking the Keep-Alive Settings for a Cluster Gateway Broker
To get the gateway Broker's current keep-alive setting for a particular cluster, you use the BrokerAdminClient.getClusterGatewayKeepAlive method. This method returns the gateway Broker's current keep-alive interval (in seconds) for a given cluster.
Pausing a Gateway Broker
To temporarily halt forwarding of events from one gateway Broker to another, you use the BrokerAdminClient.setClusterGatewayPause method. When you use this method, you specify the cluster whose events you want to hold and set the pause parameter to true.
Once you pause the forwarding of events to a particular cluster, the gateway Broker queues documents for that cluster in an event-forwarding queue. The Broker does not resume forwarding events to the remote cluster until event-forwarding is explicitly re-enabled.
Pausing Traffic in Both Directions
Be aware that the BrokerAdminClient.setClusterGatewayPause method halts the flow of traffic in one direction. That is, it stops the Broker to which the BrokerAdminClient client is connected from sending outbound messages to a specified cluster. It does not halt the flow of inbound traffic to the gateway Broker from the remote cluster. To halt both inbound and outbound between two gateway Brokers, you must execute BrokerAdminClient.setClusterGatewayPause on both Brokers.
Note that once you pause the forwarding queue for a cluster, it remains paused even if the gateway Broker is restarted or the Broker Admin client disconnects.
112 webMethods Broker Administration Java API Programmer’s Guide Version 8.2
8 Managing Broker Clusters
Pausing Traffic to and from Multiple Clusters
If a Broker serves as a gateway to multiple clusters, and you want to pause outbound traffic to all of the clusters, execute BrokerAdminClient.setClusterGatewayPause on the gateway Broker once for each remote cluster.
Similarly, if you want to halt inbound traffic to a gateway Broker from multiple remote clusters, execute BrokerAdminClient.setClusterGatewayPause on each remote gateway Broker.
Unpausing a Cluster Gateway Broker
To re-enable event forwarding, you re-execute BrokerAdminClient.setClusterGatewayPause and set the pause parameter to false.
Checking the Current Pause Setting
To check the state of event-forwarding queues on the gateway Broker, execute the BrokerAdminClient.getClusterStats method and examine the gateway_pause field in the Broker event that BrokerAdminClient.getClusterStats returns.
Static Gateway Forwarding
The static gateway forwarding feature ensures consistent document flow across a gateway between two clusters at all times. Documents defined by the gateway permissions list are allowed to flow over the gateway. Once static gateway forwarding is enabled, the documents are forwarded to the remote cluster at all times, regardless of any client subscriptions on the remote cluster.
Essentially, the static gateway forwarding feature force feeds documents to the remote cluster. When there are no subscribers on the remote cluster, forwarded documents will be dropped at the gateway peer of the remote cluster. Disabling static gateway forwarding resumes the normal behavior of subscription based gateway forwarding.
Note: The static gateway forwarding feature is only supported on a webMethods Broker Version 6.1 Service Pack 4 and later. The Broker(s) on the other end of the gateway can be of any version. In addition, you cannot enable static gateway forwarding on a Broker that is either not in a cluster or does not have a gateway to the specified remote cluster.
To enable static gateway forwarding, use the BrokerAdminClient.setClusterStaticGatewayForwarding method and set enable to true.
To check the status of the static gateway subscription set on a remote cluster from the current Broker, execute the BrokerAdminClient.getClusterStaticGatewayForwarding method.
For more information about static gateway forwarding, see Administering webMethods Broker.
webMethods Broker Administration Java API Programmer’s Guide Version 8.2 113
8 Managing Broker Clusters
Refusing Document Type Updates Across a Gateway
By default, changes made to shared document types on one side of a gateway are propagated to a Broker cluster on the other side of the gateway. However, you can configure a cluster to refuse updates made on the other side of a gateway. This setting provides the following security measures:
Lockdown of a local cluster. Unauthorized changes made in a neighboring cluster are not carried over to the local cluster.
Protection against accidental changes made to shared document types in the neighboring cluster.
Configuring a cluster to refuse updates is done at the local end of a gateway. If you want the Broker clusters on both sides of a gateway to refuse updates, you must configure the setting from both sides.
Update Refusal Classes and Methods
You have the option of refusing all changes to document types made in the neighboring cluster, or specifying which document types cannot be changed.
The following methods set and return whether a gateway refuses all updates made in a neighboring cluster: BrokerAdminClient.setClusterGatewayRefuseAllUpdates and BrokerAdminClient.getClusterGatewayRefuseAllUpdates.
Use the BrokerAdminClient.getClusterGatewaySharedEventTypes to set and return the document types for which a gateway refuses updates.
The BrokerSharedEventTypeRefuseUpdateInfo class stores information about how a particular event type is shared across a cluster gateway, and whether the event type itself or updates to the event type are refused.
Synchronizing Updates
If you turned on an update refusal setting for the local cluster and an update is made to a shared document type on the other side of the cluster gateway, all document flow to the local cluster stops. At this point, you need to synchronize the document types by using one of the methods described below:
For update refusals set on the local side of a gateway, deliver a document of the type that was refused to the remote side of the gateway.
Change the event type definition;
On the remote side of the gateway, revert the update back to the previous document type definition.
On the local side of the gateway, update the document type definition.
Turn off the update refusal flag.
After you synchronize the updates, document flow to the local cluster will restart.
114 webMethods Broker Administration Java API Programmer’s Guide Version 8.2
8 Managing Broker Clusters
Note: Broker Server issues alerts for event flow suspension and resumption.
Setting Cluster Gateway Security
For information on cluster gateway security, see “Cluster Gateway Security Configurations” on page 90.
webMethods Broker Administration Java API Programmer’s Guide Version 8.2 115
8 Managing Broker Clusters
116 webMethods Broker Administration Java API Programmer’s Guide Version 8.2
9 Managing Site Configurations
Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 118
Collection Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 118
Server Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 118
Broker Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 119
Client Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 120
Client Group Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121
Event Type Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122
Territory Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122
Territory Gateway Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123
webMethods Broker Administration Java API Programmer’s Guide Version 8.2 117
9 Managing Site Configurations
Overview
This chapter describes the webMethods Broker Java interfaces that allow you to load, store, import and export site configuration information for the following:
Broker Servers
Brokers
Clients
Client groups
Event types
Territories
Territory gateways
These interfaces work in conjunction with the ActiveWorks Definition Language (ADL), described in Administering webMethods Broker.
Note: See the webMethods Broker Client Java API Programmer’s Guide for information on naming restrictions for Brokers, client groups, event types, and territories
Collection Information
The BrokerCompleteCollection class can hold information about an entire configuration of Broker Servers, Brokers, Broker clients, client groups, event types, and access control lists.
The following table shows the methods offered by the BrokerCompleteCollection class.
Server Information
You can use the BrokerCompleteServer class to hold the following information about a Broker Server:
Method Description
read
readFile
Creates a BrokerCompleteCollection and initializes it from input data or from an input file containing ADL.
toString Returns a string of ADL that describes the collection defined by this object.
write Writes the contents of this collection, usually to a file, in ADL format.
writeVersionNumber Writes just the version number of this object.
118 webMethods Broker Administration Java API Programmer’s Guide Version 8.2
9 Managing Site Configurations
Access Control List
Brokers contained in the server
Server's description
Server's host name
Server's license key
Server's log configuration
Port number used
Server's SSL configuration
The following table shows the methods offered by the BrokerCompleteServer class.
Broker Information
You can use the BrokerCompleteBroker class to hold information about a particular Broker. The following information is stored for the Broker:
Broker's name
Names of other Brokers in the Broker's territory
Method Description
deepRefresh Refreshes this object's data members, using the specified administrative Broker client.
deepRetrieve Returns a BrokerCompleteServer object initialized using the specified administrative Broker client.
deepStore Stores the information contained in this object into a Broker Server.
refresh Refreshes this object's data members, using the specified administrative Broker client. Any information the Broker client does not have permission to access will not be set.
retrieve Returns a BrokerCompleteServer object initialized using the specified administrative Broker client. Server information is returned, but not information on the server's Brokers.
store Stores the information contained in this object into a Broker Server. Server information is stored, but not information the server's Brokers.
toString Returns a string of ADL that describes the information contained in this object.
write Writes the contents of this collection, usually to a file, in ADL format.
webMethods Broker Administration Java API Programmer’s Guide Version 8.2 119
9 Managing Site Configurations
Client groups
Clients
Broker's description
Event types
An indication if this is the default Broker
Broker's territory name
The following table shows the methods offered by the BrokerCompleteBroker class.
Client Information
You can use the BrokerCompleteClient class to hold information about a particular Broker client. The following information is stored for the Broker client:
BrokerClientInfo for the Broker client
Broker client's infoset
Broker client's event subscription list
An indication of whether or not the Broker client's event subscription list should be overwritten when the store method is invoked.
The following table shows the methods offered by the BrokerCompleteClient class.
Method Description
deepRefresh Refreshes this object's data members, using the specified administrative Broker client.
deepRetrieve Returns a BrokerCompleteBroker object initialized using the specified administrative Broker client.
deepStore Stores the information contained in this object into a Broker.
refresh Refreshes this object's data members, using the specified administrative Broker client. Any information the Broker client does not have permission to access will not be set.
retrieve Returns a BrokerCompleteBroker object initialized using the specified administrative Broker client.
store Stores most of the information contained in this object into a Broker Server.
toString Returns a string of ADL that describes the information contained in this object.
write Writes the contents of this collection, usually to a file, in ADL format.
120 webMethods Broker Administration Java API Programmer’s Guide Version 8.2
9 Managing Site Configurations
Client Group Information
You can use the BrokerCompleteClientGroup class to hold information about a particular client group. The following information is stored for the client group:
Client group's Access Control List
Names of event types this group can publish
Names of event types to which this group can subscribe
ClientGroupInfo
An indication if errors should be ignored when using the store or deepStore methods
An indication if the can-publish and can-subscribe lists should be replaced when using the store or deepStore methods
The following table shows the methods offered by the BrokerCompleteClientGroup class.
Method Description
refresh Refreshes this object's data members, using the specified administrative Broker client. Any information the Broker client does not have permission to access will not be set.
retrieve Returns a BrokerCompleteClient object initialized using the specified administrative Broker client.
store Stores most of the information contained in this object into the Broker client.
toString Returns a string of ADL that describes the information contained in this object.
write Writes the contents of this collection, usually to a file, in ADL format.
Method Description
refresh Refreshes this object's data members, using the specified administrative Broker client. Any information the Broker client does not have permission to access will not be set.
retrieve Returns a BrokerCompleteClientGroup object initialized using the specified administrative Broker client.
store Stores the information contained in this object into the Broker.
toString Returns a string of ADL that describes the information contained in this object.
write Writes the contents of this collection, usually to a file, in ADL format.
webMethods Broker Administration Java API Programmer’s Guide Version 8.2 121
9 Managing Site Configurations
Event Type Information
You can use the BrokerCompleteEventType class to hold information about a particular event type. The following information is stored for the event type:
Event types infosets
Event type's type definition
An indication if the definition should be replaced when using the store or deepStore methods
The following table shows the methods offered by the BrokerCompleteEventType class.
Territory Information
You can use the BrokerCompleteTerritory class to hold information about a territory of Brokers. For more information about territories, see “Managing Broker Territories” on page 93.
The following information is stored for territory:
Territory's Access Control List
Names of the Brokers that belong to the territory
BrokerTerritoryInfo, which contains a variety of information on the gateway, including its name, authentication type, and encryption level
The following table shows the methods offered by the BrokerCompleteTerritory class.
Method Description
refresh Refreshes this object's data members, using the specified administrative Broker client. Any information the Broker client does not have permission to access will not be set.
retrieve Returns a BrokerCompleteEventType object initialized using the specified administrative Broker client.
store Stores the information contained in this object into the Broker.
toString Returns a string of ADL that describes the information contained in this object.
write Writes the contents of this collection, usually to a file, in ADL format.
Method Description
refresh Refreshes this object's data members, using the specified administrative Broker client. Any information the Broker client does not have permission to access will not be set.
122 webMethods Broker Administration Java API Programmer’s Guide Version 8.2
9 Managing Site Configurations
Territory Gateway Information
You can use the BrokerCompleteTerritoryGateway class to hold information about a territory gateway. For more information about territory gateways, see “Managing Broker Territories” on page 93.
The following information is stored for a gateway:
The gateway's Access Control List
The names of all the shared event types that can be forwarded to the remote half of the territory gateway
The names of all the shared event types that can be received from the remote half of the territory gateway
BrokerTerritoryGatewayInfo, which contains the territory's name, authentication type, and encryption level
The following table shows the methods offered by the BrokerCompleteTerritoryGateway class.
retrieve Returns a BrokerCompleteTerritory object initialized using the specified administrative Broker client.
store Stores the information contained in this object into the Broker.
toString Returns a string of ADL that describes the information contained in this object.
write Writes the contents of this collection, usually to a file, in ADL format.
Method Description
refresh Refreshes this object's data members, using the specified administrative Broker client. Any information the Broker client does not have permission to access will not be set.
retrieve Returns a BrokerCompleteTerritory object initialized using the specified administrative Broker client.
store Stores the information contained in this object into the Broker.
toString Returns a string of ADL that describes the information contained in this object.
write Writes the contents of this collection, usually to a file, in ADL format.
Method Description
webMethods Broker Administration Java API Programmer’s Guide Version 8.2 123
9 Managing Site Configurations
124 webMethods Broker Administration Java API Programmer’s Guide Version 8.2
10 Monitoring Broker Activity
Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 126
Activity and Trace Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 126
Activity Traces . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 134
Broker Logging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 135
Broker Server Logs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 137
webMethods Broker Administration Java API Programmer’s Guide Version 8.2 125
10 Monitoring Broker Activity
Overview
This chapter describes several ways that you can monitor the activity of a Broker. Reading this chapter will help you understand:
The activity and trace events published by a Broker to which your client application can subscribe
How you use the BrokerAdminClient and BrokerTraceEvent interfaces to obtain a Broker's activity traces
How to use the BrokerLogConfig and BrokerLogEntry classes to configure the Broker's activity log
How to access and manipulate Broker Server log entries
Activity and Trace Events
The webMethods Broker system provides two sets of events that provide information about changes in a Broker; activity events and trace events. Activity events describe changes in a Brokers clients, client groups, event types, and territory affiliation. Trace events provide information about the enqueuing, publishing, and forwarding of events performed by a Broker. Administrative tools or clients that dynamically adapt to changes in a Broker's configuration are two examples of applications that may want to subscribe to these events.
Each of the activity and trace event types described in this section are only published by a Broker if at least one client has subscribed to that event type. Any client with the necessary permissions may subscribe to these events and some of them can degrade the performance of your system, so you may want to consider restricting non-administrative applications from subscribing to them.
Note: An activity or trace event can only be received by a Broker client connected to the Broker which published the event. Activity and trace events are local and will never be forwarded to another Broker. Furthermore, activity traces cannot be subscribed to using a wildcard subscription. See the webMethods Broker Client Java API Programmer’s Guide for information on subscriptions and wildcards.
For information on configuring event subscription permissions, see Administering webMethods Broker.
Note: Events are known as documents in Administering webMethods Broker.
Activity Events
Activity events provide information about the change in a Broker's configuration. These changes involve:
126 webMethods Broker Administration Java API Programmer’s Guide Version 8.2
10 Monitoring Broker Activity
Creation, disconnection, re-connection, destruction, client queue locking or unlocking for Queue Manipulation of a Broker client.
Creation, modification, or destruction of a client group.
Creation, modification, or destruction of an event type definition.
A Broker joining or leaving a territory. For more information on territories, see “Managing Broker Territories” on page 93.
Client Changes
The event type Broker::Activity::ClientChange provides information about a change in a Broker's clients. This event consists of the event fields shown in the following table.
Client Group Changes
The event type Broker::Activity::ClientGroupChange provides information about a change in a Broker's client groups. This event consists of the event fields shown in the following table.
Field Name Type Description
clientId unicode_string The identifier of the Broker client whose state has changed.
clientGroup unicode_string The Broker client's group affiliation.
appName unicode_string The application name associated with the Broker client.
stateFlags int A bit mask with one or more of the following values:
1-created
2-destroyed
4-connected
8-disconnected
16-client queue locked
32-client queue unlocked
user unicode_string The user that made the change. This will only be set if the entity making the change used an SSL connection.
authenticator unicode_string The entity that authenticated the user. This will only be set if the entity making the change used an SSL connection.
webMethods Broker Administration Java API Programmer’s Guide Version 8.2 127
10 Monitoring Broker Activity
Event Type Changes
The event type Broker::Activity::EventTypeChange provides information about a change in a Broker's event type definitions. This event consists of the event fields shown in the following table.
Territory Changes
The event type Broker::Activity::TerritoryChange provides information about a change in a Broker's territory affiliation. This event will be published by a Broker when another Broker joins or leaves its territory. The event consists of the event fields shown in the following table.
Field Name Type Description
created unicode_string[] The list of client groups that were created.
changed unicode_string[] The list of client groups that were changed. Changes may include modifications to the can-publish list, can-subscribe list, or ACL.
destroyed unicode_string[] The list of client groups that were destroyed.
changeTime date The time the change occurred.
user unicode_string The user that made the change.
authenticator unicode_string The entity that authenticated the user.
Field Name Type Description
created unicode_string[] The list of event types that were created.
defChanged unicode_string[] The list of event types whose definitions were changed.
infoChanged unicode_string[] The list of event types whose infosets were modified.
destroyed unicode_string[] The list of event types that were destroyed.
changeTime date The time the change occurred.
user unicode_string The user that made the change.
authenticator unicode_string The entity that authenticated the user.
Field Name Type Description
territoryName unicode_string The name of the Broker's territory.
brokerName unicode_string The name of the Broker.
128 webMethods Broker Administration Java API Programmer’s Guide Version 8.2
10 Monitoring Broker Activity
Trace Events
Trace events provide information about events that are passing through the system and are useful in monitoring and evaluating event traffic. Trace events themselves never cause other trace events to be generated, yet they may still add considerable overhead to your system. The same information is available through the getActivityTraces method, which will not degrade the performance of your system. Each trace event type is published only if at least one client has subscribed to that event type.
Note: Traces cannot be subscribed to using a wildcard subscription. See the webMethods Broker Client Java API Programmer’s Guide for information on subscriptions and wildcards.
Dropped Events
The event type Broker::Trace::Drop is published whenever an event was discarded by the Broker because it was delivered to a Broker client which did not have permission to receive the event. This event consists of the event fields shown in the following table.
hostName unicode_string The name of the Broker's host.
changeFlags int A bit mask with one or more of the following values:
1-jointed
2-left
4-local Broker
user unicode_string The user that made the change.
authenticator unicode_string The entity that authenticated the user.
Field Name Type Description
clientId unicode_string The Broker client's identifier.
eventTypeName unicode_string The name of the event type.
eventId long The event identifier from the event.
pubId unicode_string The identifier of the Broker client that delivered the event.
destId unicode_string The identifier of the intended recipient Broker client.
trackId unicode_string The tracking identifier from the event.
tag int The event's tag field.
eventByteSize int The size of the event in bytes.
Field Name Type Description
webMethods Broker Administration Java API Programmer’s Guide Version 8.2 129
10 Monitoring Broker Activity
Remotely Dropped Events
The event type Broker::Trace::RemoteDrop is published whenever an event was discarded by the Broker while forwarding to other territory Brokers because the event was too large to be handled by the territory Broker. This occurs in a territory consisting of 5.0 and pre 5.0 Brokers while forwarding an event of size greater than the maximum transaction size from 5.0 Broker to pre 5.0 Brokers. This event consists of the event fields shown in following table.
Enqueued Events
The event type Broker::Trace::Enqueue is published whenever the Broker places an event in a Broker client's queue. This event consists of the event fields shown in the following table.
Field Name Type Description
brokerName unicode_string The name of the remote Broker for which the event was enqueued.
brokerHost unicode_string The host name where the remote Broker is running.
eventTypeName unicode_string The name of the event type.
eventId long The event identifier from the event.
pubId unicode_string The identifier of the Broker client that delivered the event.
destId unicode_string The identifier of the intended recipient Broker client.
trackId unicode_string The tracking identifier from the event.
tag int The event's tag field.
eventByteSize int The size of the event in bytes.
Field Name Type Description
clientId unicode_string The Broker client's identifier.
eventTypeName unicode_string The name of the event type.
eventId long The event identifier from the event.
pubId unicode_string The identifier of the Broker client that delivered the event.
destId unicode_string The identifier of the intended recipient Broker client.
trackId unicode_string The tracking identifier from the event.
tag int The event's tag field.
eventByteSize int The size of the event in bytes.
130 webMethods Broker Administration Java API Programmer’s Guide Version 8.2
10 Monitoring Broker Activity
Remotely Enqueued Events
The event type Broker::Trace::EnqueueRemote is published whenever the Broker puts an event in a remote Broker's queue as part of Broker-to-Broker communication. This event consists of the event fields shown in the following table.
Published Events
The event type Broker::Trace::Publish is published whenever the Broker publishes or delivers an event. This event consists of the event fields shown in the following table.
Field Name Type Description
brokerName unicode_string The name of the remote Broker for which the event was enqueued.
brokerHost unicode_string The host name where the remote Broker is running.
eventTypeName unicode_string The name of the event type.
eventId long The event identifier from the event.
pubId unicode_string The identifier of the Broker client that delivered the event.
destId unicode_string The identifier of the intended recipient Broker client.
trackId unicode_string The tracking identifier from the event.
tag int The event's tag field.
eventByteSize int The size of the event in bytes.
Field Name Type Description
clientId unicode_string The Broker client's identifier.
eventTypeName unicode_string The name of the event type.
eventId long The event identifier from the event.
pubId unicode_string The identifier of the Broker client that delivered the event.
destId unicode_string The identifier of the intended recipient Broker client.
trackId unicode_string The tracking identifier from the event.
tag int The event's tag field.
eventByteSize int The size of the event in bytes.
webMethods Broker Administration Java API Programmer’s Guide Version 8.2 131
10 Monitoring Broker Activity
Remotely Published Event
The event type Broker::Trace::PublishRemote is published whenever the Broker receives a published event from a remote Broker. This event consists of the event fields shown in the following table.
Received Events
The event type Broker::Trace::Receive is published whenever a Broker client acknowledges an event that it has retrieved from its client queue. This event consists of the event fields shown in the following table.
Field Name Type Description
brokerName unicode_string The name of the remote Broker for which the event was enqueued.
brokerHost unicode_string The host name where the remote Broker is running.
eventTypeName unicode_string The name of the event type.
eventId long The event identifier from the event.
pubId unicode_string The identifier of the Broker client that delivered the event.
destId unicode_string The identifier of the intended recipient Broker client.
trackId unicode_string The tracking identifier from the event.
tag int The event's tag field.
eventByteSize int The size of the event in bytes.
Field Name Type Description
clientId unicode_string The Broker client's identifier.
eventTypeName unicode_string The name of the event type.
eventId long The event identifier from the event.
pubId unicode_string The identifier of the Broker client that published the event.
destId unicode_string The identifier of the intended recipient Broker client.
trackId unicode_string The tracking identifier from the event.
tag int The event's tag field.
eventByteSize int The size of the event in bytes.
132 webMethods Broker Administration Java API Programmer’s Guide Version 8.2
10 Monitoring Broker Activity
Remotely Received Event
The event type Broker::Trace::ReceiveRemote is published whenever a remote Broker acknowledges the receipt of a forwarded event. This event consists of the event fields shown in the following table.
Peek Events
The event type Broker::Trace::Peek is published whenever an event is peeked administratively from the Broker client's queue. This event consists of the event fields shown in the following table.
Field Name Type Description
brokerName unicode_string The name of the remote Broker.
brokerHost unicode_string The host name where the remote Broker is running.
eventTypeName unicode_string The name of the event type.
eventId long The event identifier from the event.
pubId unicode_string The identifier of the Broker client that published the event.
destId unicode_string The identifier of the intended recipient Broker client.
trackId unicode_string The tracking identifier from the event.
tag int The event's tag field.
eventByteSize int The size of the event in bytes.
Field Name Type Description
clientId unicode_string The Broker client's identifier.
eventTypeName unicode_string The name of the event type.
eventId long The event identifier from the event.
lockingId unicode_string The identifier of the Broker client that is holding a queue lock on this client.
trackId unicode_string The tracking identifier from the event.
tag int The event's tag field.
eventByteSize int The size of the event in bytes.
webMethods Broker Administration Java API Programmer’s Guide Version 8.2 133
10 Monitoring Broker Activity
Insert Events
The event type Broker::Trace::Insert is published whenever an event is inserted administratively into the Broker client's queue. This event consists of the event fields shown in the following table.
Delete Events
The event type Broker::Trace::Delete is published whenever an event is deleted administratively from the Broker client's queue. This event consists of the event fields shown in the following table.
Activity Traces
Each Broker maintains its own set of activity traces. Activity traces require very little overhead and will not degrade the performance of your system. However, activity traces can be lost if the Broker is very busy or if your client does not retrieve them quickly enough.
A BrokerTraceEvent is created by a Broker whenever one of the following occurs:
Field Name Type Description
clientId unicode_string The Broker client's identifier.
eventTypeName unicode_string The name of the event type.
eventId long The event identifier from the event.
lockingId unicode_string The identifier of the Broker client that is holding a queue lock on this client.
trackId unicode_string The tracking identifier from the event.
tag int The event's tag field.
eventByteSize Int The size of the event in bytes.
Field Name Type Description
clientId unicode_string The Broker client's identifier.
eventTypeName unicode_string The name of the event type.
eventId long The event identifier from the event.
lockingId unicode_string The identifier of the Broker client that is holding a queue lock on this client.
trackId unicode_string The tracking identifier from the event.
tag int The event's tag field.
eventByteSize int The size of the event in bytes.
134 webMethods Broker Administration Java API Programmer’s Guide Version 8.2
10 Monitoring Broker Activity
A Broker client or remote Broker is created or destroyed.
A Broker client or remote Broker publishes or delivers an event.
A Broker client or remote Broker retrieves an event from its event queue.
A Broker adds an event to a client's or remote Broker's event queue.
An event was dropped from a Broker client's queue because the client did not have permission to receive the event.
Understanding the BrokerTraceEvent
The BrokerTraceEvent class represents an entry in a Broker's activity trace. Some of the information that may be contained in a trace event includes:
A key indicating the trace event's type
The name of the client application
The name of the Broker Server
The name of the Broker host
The application's client group and client identifier, if applicable
The event type name
The event's _env.tag field, destination ID, and receiving client ID
The client identifier of the destination client, if applicable
Obtaining Activity Traces
You can use the BrokerAdminClient.getActivityTraces method to obtain an array of BrokerTraceEvent objects. You must supply the sequence number of the first trace event to be retrieved and the number of milliseconds to wait if no trace information is available.
The first time you invoke this method, the sequence number should be set to zero. On subsequent invocations of this method, you should set the sequence number one plus the value of the last trace event's sequence number.
Broker Logging
Each Broker maintains a log containing three levels of failure messages, which may be configured individually.
Level Description
Alert Identifies critical messages.
Warning Identifies important messages.
webMethods Broker Administration Java API Programmer’s Guide Version 8.2 135
10 Monitoring Broker Activity
The Broker's log may use any of the following logging mechanisms:
Unix syslog facility
Windows NT event log
SNMP alerts
Understanding the BrokerLogConfig
You can use the BrokerServerClient.getLogConfig method to obtain the logging configuration for a Broker Server. The BrokerServerClient.setLogConfig method allows you to set the logging configuration for a Broker Server.
The BrokerLogConfig class represents the Broker Server's logging configuration and provides methods that allow you to:
Obtain log configuration entries by topic.
Obtain the entire contents of the log configuration.
Remove a single entry from the log configuration or remove all entries.
Remove log configuration entries by topic
The following table shows the methods offered by the BrokerLogConfig class.
Informational Identifies informational messages.
Method Description
clearLogOutput
clearLogOutputs
Clears one or more entries from a specified log output.
clearLogTopic
clearLogTopics
Clears one or more entries from a specified log topic.
getLogOutput
clearLogOutputs
Returns one or more BrokerLogEntry objects which represent the state of the specified log output or outputs.
getLogTopic
getLogTopics
Returns one or more BrokerLogEntry objects which represent the state of the specified log topic or topics.
setLogOutput Sets the value of a log output's state.
setLogTopic Sets the value of a log topic's state.
toString Returns a string containing the log configuration in a human-readable format.
Level Description
136 webMethods Broker Administration Java API Programmer’s Guide Version 8.2
10 Monitoring Broker Activity
Understanding the BrokerLogEntry
The BrokerLogConfigEntry class represents the settings for an instance of a log output or a log topic. It contains the following information:
The type of log output or topic being represented.
An indication of whether or not the output or topic is enabled.
An optional string containing additional information.
Broker Server Logs
Each Broker Server maintains a log of significant events that have occurred. The format of each entry described by the BrokerServerLogEntry object is shown in the following table.
Each Broker Server log entry is assigned a type as defined in the following table.
Obtaining Log Entries
You can use the BrokerServerClient.getServerLogEntries method to obtain a desired set of entries from the log of the Broker Server to which your client is connected. This method lets you specify the date of the first entry in which you are interested and the total number of entries you wish to retrieve.
Note: Attempting to obtain all server log entries may create performance problems and may use up significant amounts of memory.
Field Name Type Description
time_stamp BrokerDate The date and time that the entry was created.
entry_type short The entry's type. See the next table, below, for a list of possible types.
entry_mesg_id short The message identifier.
entry_msg_text char * The event identifier from the event.
Constant Description
SERVER_LOG_MESSAGE_UNKNOWN The entry has an undefined type.
SERVER_LOG_MESSAGE_INFO The entry contains an informational message.
SERVER_LOG_MESSAGE_WARNING The entry contains a warning message.
SERVER_LOG_MESSAGE_ALERT The entry contains an alert message.
webMethods Broker Administration Java API Programmer’s Guide Version 8.2 137
10 Monitoring Broker Activity
The BrokerServerLogEntry.toString method allows you to convert a BrokerServerLogEntry to a character string.
Obtaining Log Information
The BrokerServerLogInfo object describes basic information about a particular server's log. The following table describes the contents of the BrokerServerLogInfo object.
You can use the BrokerServerClient.getServerLogStatus method to obtain the status of the log of the Broker Server to which your client is connected.
Deleting Log Entries
You can use the BrokerServerClient.pruneServerLog method to delete selected entries from the log of the Broker Server to which your client is connected. All entries with dates equal to or older than the date you specify will be deleted.
Field Name Type Description
num_entries int The number of entries contained in the log.
first_entry BrokerDate The date and time of the earliest entry contained in the log.
last_entry BrokerDate The date and time of the most recent entry contained in the log.
138 webMethods Broker Administration Java API Programmer’s Guide Version 8.2
11 Queue Browser
Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 140
Client Queue Browser . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 140
Using Client Queue Browser . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 141
Forwarding Queue Browser . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 142
Using Forwarding Queue Browser . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 144
BrokerAdminClient . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 145
BrokerClient . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 145
BrokerQueueBrowser and BrokerClientQueueBrowser . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 146
BrokerLockedQueueBrowser and BrokerLockedClientQueueBrowser . . . . . . . . . . . . . . . . . . . . 147
Creating and Closing Client Queue Browsers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 148
Creating and Closing Forwarding Queue Browsers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 151
Acquiring a Queue Lock . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 153
Releasing a Queue Lock . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 153
Queue Position . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 153
Filters on a Queue Browser . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 154
Viewing Queue Content . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 158
Rearranging Queue Content . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 166
webMethods Broker Administration Java API Programmer’s Guide Version 8.2 139
11 Queue Browser
Overview
This chapter describes several ways by which you manage client queues. Reading this chapter will help you understand:
How to use BrokerQueueBrowser, BrokerLockedQueueBrowser, BrokerQueueBrowserInfo, and BrokerClient and BrokerAdminClient classes to examine a queue's content.
How to rearrange the contents of the client queue by adding, deleting, and replacing documents.
How to rearrange the contents of the forwarding queue for a remote Broker by adding, deleting, and replacing documents.
Note: Broker events are called Broker documents types in Software AG Designer and other webMethods components.
Client Queue Browser
webMethods Broker Java API 5.x and 6.1 provided the queue manipulation API with a limited ability to manipulate the contents of a client queue. In webMethods Broker Java API 6.5 and later, the queue manipulation API is replaced with the client queue browser API, which supports queue management in a much more robust manner. The following are the key differences between the new queue browser and the former queue manipulation feature.
The client queue browser supports three distinct modes of operation:
1 A client can inspect its own queue contents without requiring any administrative privileges.
2 An administrative client can inspect a client queue without acquiring the client's queue lock.
3 An administrative client can acquire a queue lock and perform an "in-place" replacement of documents in the locked queue, in addition to the usual insert, delete and browse operations.
You can perform four operations with the queue browser. Note that you can only perform the last three operations on a locked queue.
1 The browse operation to return queued documents, including the documents that have been retrieved but are not yet acknowledged (i.e., "unacknowledged") documents. You can apply filtering on browse operations.
2 The insert operation to add documents to either the head or tail of a locked queue.
3 The delete operation to delete documents based on their receipt sequence numbers.
140 webMethods Broker Administration Java API Programmer’s Guide Version 8.2
11 Queue Browser
4 The modify operation to replace documents "in-place" based on their receipt sequence numbers.
Using Client Queue Browser
Client queue browser works in three different modes.
1 Client queue browser. A client can open a queue browser on its own queue and browse documents without requiring any administrative privileges. A client queue browser requires a dedicated client session and allows browse operations on the queue from any queue position and exposes all documents in the queue.
2 Administrative Queue Browser - Unlocked Mode. An administrative queue browser allows an administrative client to access the contents of a client queue owned by a different client at runtime. In the unlocked browse mode the client queue is not locked, meaning that the queue content could change between queue browser operations. In this unlocked mode, queue browsing is the only operation the administrative client can perform. The existence of an administrative queue browser in an unlocked mode does not impact the normal functioning of the client queue.
3 Administrative Queue Browser - Locked Mode. An administrative queue browser allows an administrative client to access the contents of a client queue owned by a different client at runtime. In this mode, the client queue is locked for the lifetime of the queue browser. You can browse queue contents, delete documents from queue, insert new documents into the queue, and modify documents in the queue.
In order to invoke any queue browser operation on a client queue, you must first create a client queue browser using one of the following methods:
BrokerClient.createClientQueueBrowser()
Broker client creates a queue browser to browse its own queue.
BrokerAdminClient.createClientQueueBrowser()
Broker administrative client creates a queue browser to browse another client's queue
BrokerAdminClient.createLockedClientQueueBrowser()
Broker administrative client creates a queue browser to manipulate the contents of another client's queue.
These functions will return a queue browser that can be used to invoke various queue management functions on the client queue.
Note: Pre-6.5 Brokers do not support the queue browser API. You will receive an error if your client attempts to open a queue browser on pre-6.5 versions of Broker clients.
The BrokerClientQueueBrowserInfo object represents information of a client queue browser with data members described in the following table.
webMethods Broker Administration Java API Programmer’s Guide Version 8.2 141
11 Queue Browser
Forwarding Queue Browser
webMethods Broker Java API 8.1 and later provides an API to view the contents of a forwarding queue for a remote Broker. The forwarding queue browser supports two distinct modes of operation:
1 An administrative client can inspect a forwarding queue without acquiring the client's queue lock.
2 An administrative client can acquire a queue lock and perform browse, delete, insert, and modify operations.
You can perform four operations with the queue browser. Note that you can only perform the last three operations on a locked queue.
1 The browse operation to return queued documents, including the documents that have been retrieved but are not yet acknowledged (i.e., "unacknowledged") documents. You can apply filtering on browse operations.
2 The insert operation to add documents to the tail of a locked queue.
Note: You cannot insert documents to the head of a forwarding queue for a remote Broker.
3 The delete operation to delete documents based on their receipt sequence numbers.
4 The modify operation to replace documents "in-place" based on their receipt sequence numbers.
In addition to regular documents, the forwarding queue for a remote Broker might also contain internal events that Broker uses to perform tasks such as territory synchronization, and subscription updates. Internal events are produced only by Brokers and consumed only by peer Brokers in a territory, cluster, or a gateway Broker. Regular
Data Member Description
String clientId This member contains the ID of the client on which the queue browser is currently open. For information on client IDs, see “Queue Browser” on page 139.
String browserId This member contains the ID of the client that created the queue browser. For information on client IDs, see “Queue Browser” on page 139.
int browserSessionId
This member contains the session ID of the client that created the queue browser.
boolean locked The value is set to true if the client queue is locked by this queue browser; otherwise, false.
int createTime This member contains the date and time when the queue browser was created.
142 webMethods Broker Administration Java API Programmer’s Guide Version 8.2
11 Queue Browser
clients cannot process internal events because internal events are not associated with any Broker event type. The queue browser skips all internal events while returning documents from a forwarding queue as explained in the following diagram.
webMethods Broker Administration Java API Programmer’s Guide Version 8.2 143
11 Queue Browser
In this illustration, if you set the cursor position to "2" and request six events, the queue browser returns only four events namely, Regular Event 3, Regular Event 4, Regular Event 5, and Regular Event 6. This behavior occurs because the events at cursor position 2 and cursor position 3 are internal events. The queue browser skips these events and returns the remaining events from the forwarding queue.
You can delete regular events from the forwarding queue for a remote Broker, but you cannot delete internal events. An internal event might contain metadata changes. So deleting an internal event would mean that the regular events that come next in the queue might not be consumed successfully by the subscribers due to metadata mismatch.
Using Forwarding Queue Browser
Forwarding queue browser works in two modes.
1 Administrative Queue Browser - Unlocked Mode. An administrative queue browser allows an administrative client to access the contents of a forwarding queue for a remote Broker at runtime. In the unlocked browse mode the forwarding queue is not locked, meaning that the queue content could change between queue browser operations. In this unlocked mode, queue browsing is the only operation the administrative client can perform. The existence of an administrative queue browser in an unlocked mode does not impact the normal functioning of the forwarding queue.
2 Administrative Queue Browser - Locked Mode. An administrative queue browser allows an administrative client to access the contents of a forwarding queue for a remote Broker at runtime. In this mode, the forwarding queue is locked for the lifetime of the queue browser. You can browse queue contents, delete documents from queue, insert new documents into the queue, and modify documents in the queue.
To invoke a queue browser operation on the forwarding queue, the Broker administrative client must first create a forwarding queue browser using the BrokerAdminClient.createForwardQueueBrowser() method.
To invoke a queue browser operation on the forwarding queue, the Broker administrative client must first create a forwarding queue browser using one of the following methods:
BrokerAdminClient.createForwardQueueBrowser()
Broker administrative client creates a queue browser to browse forwarding queue.
BrokerAdminClient.createLockedForwardQueueBrowser()
Broker administrative client creates a queue browser to manipulate the contents of a forwarding queue.
This method will return a queue browser that you use to invoke various queue management functions on the queue.
Note: Brokers earlier than version 8.1 do not support the queue browser APIs.
144 webMethods Broker Administration Java API Programmer’s Guide Version 8.2
11 Queue Browser
The BrokerQueueBrowserInfo object represents information of a queue browser with data members described in the following table.
BrokerAdminClient
The BrokerAdminClient class is used to represent a Broker administrative client. For more information about the BrokerAdminClient class, see Chapter 4, “Managing Broker Clients”.
You use the createClientQueueBrowser and createLockedClientQueueBrowser methods in the BrokerAdminClient class to create queue browsers on a specific client in unlocked and locked modes, respectively.
You use the createForwardQueueBrowser method to create a queue browser on a specific forward queue for a remote Broker in unlocked mode and createLockedForwardQueueBrowser method in locked mode.
BrokerClient
The BrokerClient class is used to represent a Broker client. For more information about the BrokerClient class, see Chapter 4, “Managing Broker Clients”.
You use the createClientQueueBrowser method in BrokerClient to create a queue browser on the client's own queue. Once you create a queue browser from a client session, that session will be marked as a queue browsing session and cannot be used to retrieve documents from the queue using regular document retrieval methods. Hence, wherever possible, you must create a queue browser on a separate client session.
Note: You cannot use the BrokerClient class to create a queue browser on the forwarding queue for a remote Broker; use the BrokerAdminClient class instead.
Data Member Description
String clientId This member contains the ID of the client or remote Broker on which the queue browser is currently open.
String browserId This member contains the ID of the client that created the queue browser. For information on client IDs, see “Queue Browser” on page 139.
int browserSessionId
This member contains the session ID of the client that created the queue browser.
boolean locked The value is set to true if the client queue is locked by this queue browser; otherwise, false.
int createTime This member contains the date and time when the queue browser was created.
webMethods Broker Administration Java API Programmer’s Guide Version 8.2 145
11 Queue Browser
BrokerQueueBrowser and BrokerClientQueueBrowser
Note: BrokerQueueBrowser is an interface for queue browser methods, implementations of which allow you to browse both client queue and forwarding queue. BrokerQueueBrowser interface has two implementations, BrokerClientQueueBrowser for browsing client queues and BrokerForwardQueueBrowser for forwarding queues.
You use the BrokerQueueBrowser interface to access all the methods that you can use to browse a queue.
An application can use the BrokerQueueBrowser interface to perform the following functions on the client queue:
Browse documents in the client's queue.
Selectively browse documents using filters.
An application can use the BrokerQueueBrowser interface to perform the following functions on the forwarding queue for the remote Broker:
Browse documents in the forwarding queue for the remote Broker queue.
Selectively browse documents using filters.
All methods throw BrokerQueueBrowserException (and other exceptions) when necessary.
The BrokerQueueBrowser interface methods are listed in the following table.
Method Description
getBrowserInfo Get browser information of the current queue browser.
setPosition Set the browse cursor to the specified position in the queue.
Note: While setting the position of the browse cursor in a forwarding queue, keep in mind that the queue might also contain Broker internal events. For more information, see “Forwarding Queue Browser” on page 142.
setFilter Set up a single filter for queue browse operations. If the queue browser already has one or more filters, this new filter is added to the list. If a filter is already present for a document type, the existing filter will be overwritten with the new filter. When one or more filters are set on the queue browser, a browse operation only returns documents matching those filters. Note that queue browser filters are applicable only to the browse operation and not to other queue browser operations, such as insert or delete operations.
146 webMethods Broker Administration Java API Programmer’s Guide Version 8.2
11 Queue Browser
BrokerLockedQueueBrowser and BrokerLockedClientQueueBrowser
Note: BrokerLockedQueueBrowser is the interface for queue browser methods, implementations of which allow you to browse both client queue and forwarding queue. BrokerLockedQueueBrowser interface has two implementations, BrokerLockedClientQueueBrowser for browsing client queues and BrokerLockedForwardQueueBrowser for forwarding queues.
BrokerLockedQueueBrowser extends the BrokerQueueBrowser interface. In addition to browsing the queue, the BrokerLockedQueueBrowser interface allows you to manipulate the contents of the queue.
setFilters Set up a multiple filters for queue browse operations. If the queue browser already has one or more filters, the new filters are added to the list. If a filter is already present for a document type, the existing filter will be overwritten with the new filter. When filters are set on the queue browser, a browse operation only returns documents matching those filters. Note that queue browser filters are applicable only to the browse operation and not to other queue browser operations, such as insert or delete operations.
resetFilters Reset the filter list on the current queue browser. The filter list on the queue browser will be emptied out.
getFilters Get filters that are currently set for queue browse operation. The existing filters are returned in the form of BrokerFilterDescriptor objects.
browseEvents Read one or more documents from the queue on which the queue browser is opened. This method simply returns documents from the current queue position. The number of documents being returned is not guaranteed to be the requested number of documents, even if the queue contains more than that many documents. Any number of documents up to the value of max_events may be returned.
Note: While returning the documents, the queue browser skips all the internal events that might be queued in a forwarding queue. For more information, see “Forwarding Queue Browser” on page 142.
closeQueueBrowser Close the queue browser and release the associated resources.
Method Description
webMethods Broker Administration Java API Programmer’s Guide Version 8.2 147
11 Queue Browser
An application might use the BrokerLockedQueueBrowser interface to perform the following functions on the forwarding queue for a remote Broker, and the client queue.
Obtain a queue lock to manage a client queue.
Browse documents in the locked client's queue.
Modify documents in the locked client's queue.
Insert documents into the locked client's queue.
Delete documents from the locked client's queue.
Set filters for browse and delete operations.
Release an acquired queue lock.
All methods throw BrokerQueueBrowserException (and other exceptions) when necessary.
The additional methods that are available only on BrokerLockedQueueBrowser are listed in the following table. For more information, see BrokerLockedQueueBrowser on page 385.
All methods throw BrokerQueueBrowserException (and other exceptions) when necessary.
Creating and Closing Client Queue Browsers
Use the following methods to create and close client queue browsers in each mode.
For a Client Queue Browser
Create a queue browser using the BrokerClient.createClientQueueBrowser() method. This method creates a queue browser on the client's queue.
Note: This mode of operation does not require a client queue to be locked; therefore the client queue content can undergo changes while the queue browser is open.
Close the queue browser using the BrokerClientQueueBrowser.closeClientQueueBrowser() method.
Method Description
modifyEvents Modify documents in the queue. The documents are identified by the specified receipt sequence numbers for an in-place replacement in the queue.
deleteEvents Delete documents in the queue. The documents are identified by the receipt sequence numbers.
insertEventsAtHead Insert documents into the queue at head position.
insertEventsAtTail Insert documents into the queue at tail position.
148 webMethods Broker Administration Java API Programmer’s Guide Version 8.2
11 Queue Browser
The following example illustrates how to create a client queue browser on client's own queue:
BrokerClient client = null; BrokerClientQueueBrowser browser = null; //Create a Broker client try { client = new BrokerClient(broker_host, broker_name, client_id, client_group, "QueueBrowser - SELF", null); } catch(BrokerException ex) { System.out.println("Failed to create client."); return; } . . . //Create a queue browser try { browser = client.createClientQueueBrowser(); } catch(BrokerException ex) { System.out.println("Failed to create client queue browser."); return; } . . . //Various queue browser operations . . . //Close the queue browser try { browser.closeQueueBrowser(); } catch(BrokerException ex) { System.out.println("Failed to close client queue browser."); return; }
For an Administrative Queue Browser With No Lock
Create a queue browser using the BrokerAdminClient.createClientQueueBrowser() method. This creates an administrative queue browser on the client's queue.
Note: This mode of operation does not require a client queue to be locked; therefore the client queue content can undergo changes while the queue browser is open.
Close the queue browser using BrokerClientQueueBrowser.closeQueueBrowser() method.
The following example illustrates how to create an administrative queue browser on a client queue (UNLOCKED mode):
BrokerClient client = null; BrokerAdminClient admin = null; BrokerClientQueueBrowser browser = null; //Create a Broker client
webMethods Broker Administration Java API Programmer’s Guide Version 8.2 149
11 Queue Browser
try { client = new BrokerClient(broker_host, broker_name, client_id, client_group, "QueueBrowser ", null); } catch(BrokerException ex) { System.out.println("Failed to create client."); return; } //Create a Broker admin client try { admin = new BrokerAdminClient(broker_host, broker_name, null, "admin", "QueueBrowser-UNLOCKED", null); } catch(BrokerException ex) { System.out.println("Failed to create admin client."); return; } . . . //Create a queue browser in unlocked mode try { browser = admin.createClientQueueBrowser(client.getId()); } catch(BrokerException ex) { System.out.println("Failed to create client queue browser."); return; } . . . //Various browse operations . . . //Close the queue browser try { browser.closeQueueBrowser(); } catch(BrokerException ex) { System.out.println("Failed to close client queue browser."); return; }
For a Administrative Queue Browser With a Lock
Create a queue browser using the BrokerAdminClient.createLockedClientQueueBrowser() method. This method creates a locked administrative queue browser on the client's queue.
Close the queue browser using the BrokerClientQueueBrowser.closeQueueBrowser() method.
The following example illustrates how to create an administrative queue browser on a client queue (LOCKED mode):
BrokerClient client = null; BrokerAdminClient admin = null; BrokerLockedClientQueueBrowser browser = null;
150 webMethods Broker Administration Java API Programmer’s Guide Version 8.2
11 Queue Browser
//Create a Broker client try { client = new BrokerClient(broker_host, broker_name, client_id, client_group, "QueueBrowser", null); } catch(BrokerException ex) { System.out.println("Failed to create client."); return; } //Create a Broker admin client try { admin = new BrokerAdminClient(broker_host, broker_name, null, "admin", "QueueBrowser-LOCKED", null); } catch(BrokerException ex) { System.out.println("Failed to create admin client."); return; } . . . //Create a locked queue browser try { browser = admin.createLockedClientQueueBrowser(client.getId()); } catch(BrokerException ex) { System.out.println("Failed to create locked client queue browser."); return; } . . . //Various queue browser operations . . . //Close the queue browser try { browser.closeQueueBrowser(); } catch(BrokerException ex) { System.out.println("Failed to close client queue browser."); return; }
Creating and Closing Forwarding Queue Browsers
Use the following methods to create and close forwarding queue browsers in unlocked mode.
webMethods Broker Administration Java API Programmer’s Guide Version 8.2 151
11 Queue Browser
For an Administrative Queue Browser With No Lock
Create a queue browser using the BrokerAdminClient.createForwardQueueBrowser() method. This creates an administrative queue browser on the forwarding queue for the remote Broker.
Note: This mode of operation does not require a queue to be locked; therefore the queue content can undergo changes while the queue browser is open.
Close the queue browser using BrokerClientQueueBrowser.closeQueueBrowser() method.
The following example illustrates an administrative queue browser on a forwarding queue (UNLOCKED mode):
BrokerAdminClient admin = null; BrokerQueueBrowser browser = null; //Create a Broker admin client try { admin = new BrokerAdminClient(broker_host, broker_name, null, "admin", "ForwardQueueBrowser-UNLOCKED", null); } catch(BrokerException ex) { System.out.println("Failed to create admin client."); return; } . . . //Create a queue browser in unlocked mode try { browser = admin.createForwardQueueBrowser(remote_broker_name); } catch(BrokerException ex) { System.out.println("Failed to create forward queue browser."); return; } . . . //Various browse operations . . . //Close the queue browser try { browser.closeQueueBrowser(); } catch(BrokerException ex) { System.out.println("Failed to close forward queue browser."); return; }
152 webMethods Broker Administration Java API Programmer’s Guide Version 8.2
11 Queue Browser
Acquiring a Queue Lock
When you create a BrokerLockedQueueBrowser the target queue is automatically locked. Information on the queue browser can be obtained with getBrowserInfo call. One of the members of the BrokerQueueBrowserInfo indicates whether the queue is locked or not ('locked'). If the target queue is already locked by another admin client, an exception will be thrown. A queue cannot be locked by more than one admin client at any given time.
After the target queue is locked, the target queue maintains a "QueueLocked" state, which prevents certain operation from changing the queue state. For example:
A getEvent(s) call on a locked target client queue will timeout.
Events from a locked forwarding queue will not be delivered to the target remote Broker.
A clear client queue operation will be rejected with an error message notifying the client queue locked status.
A client or session disconnect (via the Broker Administrator tool) or client destroy commands will be rejected. An error message will be returned, notifying that the queue is locked.
A command such as "leave territory" that destroys a forwarding queue for a remote Broker is rejected. An error message will be returned, notifying that the queue is locked.
All acknowledgements, both implicit and explicit, will be processed. The delete and modify queue browser operations only consider the deliverable documents for operation.
Releasing a Queue Lock
When you close a BrokerLockedQueueBrowser the target queue is automatically unlocked. If the administrative client that is holding the queue lock for some reason disconnects or is deleted, the queue lock will be automatically released. Once the queue is unlocked, all the requests from the client are honored.
Queue Position
The browse operation of a queue browser is a position-based operation. A queue browser internally maintains a cursor that points to a valid queue position anywhere between the head to the tail of the queue (between 0 to "queue length minus one"). Upon creation of a queue browser, the cursor is set to point to the head of the queue. After the browse operation, the cursor then points to the next document position for the following browse operation.
webMethods Broker Administration Java API Programmer’s Guide Version 8.2 153
11 Queue Browser
For example, if the cursor points to a queue position of 200 and the browse operation is for 10 documents, the queue browser returns 10 documents from the current position of 200 to position 209. After the browse operation, the cursor is now pointing at position 210 in the queue for the next browse operation.
You can alter queue position at any point of time using the setPosition method. Any subsequent browse operation will start browsing documents from that queue position.
The following example illustrates how to set the cursor position to queue position 200:
BrokerQueueBrowser browser = null; . . . //Create a queue browser ... //Set queue position try { browser.setPosition( 200);//Set at queue position 200 } catch(BrokerException ex) { System.out.println("Failed to set queue position."); return; } . . . //Various queue browser operations . . . //Close the queue browser try { browser.closeQueueBrowser(); } catch(BrokerException ex) { System.out.println("Failed to close queue browser."); return; }
Filters on a Queue Browser
You can set and reset filters on a queue browser at any time during the lifetime of the queue browser. A browse operation will return only the documents that satisfy the filters, if any are set on the browser.
For example, the queue myQ has 10 documents and 3 contain the string "Hello webMethods!". When a filter for the string "Hello" is applied to myQ, all subsequent browse operations will return only on the three documents containing "Hello webMethods!".
Note that queue browser filters are applicable only to the browse operation and not other queue browser operations, such as insert or delete operations. One or more filters can be set at any time during the queue browsing session. Use BrokerFilterDescriptor object to describe filters. For more information, see BrokerFilterDescriptor on page 374.
The following APIs are provided for setting filters on a queue browser.
154 webMethods Broker Administration Java API Programmer’s Guide Version 8.2
11 Queue Browser
Setting a Single Filter on Queue Browser
Use the setFilter method to set up a single filter for queue browse operations. If the queue browser already has one or more filters, this new filter is added to the list. If a filter is already present for a document type, the existing filter will be overwritten with the new filter. When one or more filters are set for the queue browse operations, only documents matching those filters are processed.
The following example illustrates how to set a single filter:
BrokerAdminClient admin = null; BrokerQueueBrowser browser = null; BrokerFilterDescriptor filter =
new BrokerFilterDescriptor(""API::Test", "test_int < 10"); . . . //Create a Broker admin client try { admin = new BrokerAdminClient(broker_host, broker_name, null, "admin", "QueueBrowser-UNLOCKED", null); } catch(BrokerException ex) { System.out.println("Failed to create admin client."); return; } //Create a queue browser . . . //Set single filter try { browser.setFilter(filter); } catch(BrokerException ex) { System.out.println("Failed to set filter."); } . . . //Various browse operations . . . //Close the queue browser try { browser.closeQueueBrowser(); } catch(BrokerException ex) { System.out.println("Failed to close queue browser."); return; }
Setting Multiple Filters on Queue Browser
Use the setFilters method to set up multiple filters for queue browse operations. Note that queue browser filters are applicable only to the browse operation and not other queue browser operations, such as insert or delete operations.
webMethods Broker Administration Java API Programmer’s Guide Version 8.2 155
11 Queue Browser
If the queue browser already has one or more filters, the new filters are added to the list. If a filter is already present for a document type, the existing filter will be overwritten with the new filter. When filters are set for the queue browse operations, only documents matching those filters are processed.
The following example illustrates how to set multiple filters:
BrokerAdminClient admin = null; BrokerQueueBrowser browser = null; BrokerFilterDescriptor[] filters = new BrokerFilterDescriptor[3]; filters[0] = new BrokerFilterDescriptor(""API::Test", "test_int < 10"); filters[1] = new BrokerFilterDescriptor(""API::Test1",
"my_string.contains("Hello")); filters[2] = new BrokerFilterDescriptor(""API::Test2", "test_byte%2 == 0")); //Create a Broker admin client try { admin = new BrokerAdminClient(broker_host, broker_name, null, "admin", "QueueBrowser-UNLOCKED", null); } catch(BrokerException ex) { System.out.println("Failed to create admin client."); return; } . . . //Create a queue browser . . . //Set multiple filters try { browser.setFilters(filters); } catch(BrokerException ex) { System.out.println("Failed to set multiple filters."); } . . . //Various browse operations . . . //Close the queue browser try { browser.closeQueueBrowser(); } catch(BrokerException ex) { System.out.println("Failed to close queue browser."); return; }
Resetting Filters on Queue Browser
Use the resetFilters method to reset the filter list on the current queue browser. The filter list on the queue browser will be emptied out. Once the filters are reset, a browse request will return all documents with no filtering applied.
The following example illustrates how to reset filters:
156 webMethods Broker Administration Java API Programmer’s Guide Version 8.2
11 Queue Browser
BrokerAdminClient admin = null; BrokerQueueBrowser browser = null; //Create a Broker admin client try { admin = new BrokerAdminClient(broker_host, broker_name, null, "admin", "QueueBrowser-UNLOCKED", null); } catch(BrokerException ex) { System.out.println("Failed to create admin client."); return; } . . . //Create a queue browser in locked or unlocked mode ... //Reset filters try { browser.resetFilters(); } catch(BrokerException ex) { System.out.println("Failed to reset filters."); } . . . //Various browse operations . . . //Close the queue browser try { browser.closeQueueBrowser(); } catch(BrokerException ex) { System.out.println("Failed to close queue browser."); return; }
Viewing Currently Set Filters on Queue Browser
Use the getFilters method to view the current filter set on the client queue lock. The filters are returned as BrokerFilterDescriptor objects.
The following example illustrates how to view set filters:
BrokerAdminClient admin = null; BrokerQueueBrowser browser = null; BrokerFilterDescriptor[] inFilters = null; BrokerFilterDescriptor[] outFilters = null; //Create a Broker admin client try { admin = new BrokerAdminClient(broker_host, broker_name, null, "admin", "QueueBrowser-UNLOCKED", null);
webMethods Broker Administration Java API Programmer’s Guide Version 8.2 157
11 Queue Browser
} catch(BrokerException ex) { System.out.println("Failed to create admin client."); return; } . . . //Create a queue browser in locked or unlocked mode ... // Set filters on browser browser.setFilters(inFilters); . . . //Various browse operations . . . //Get filters applied on browser try { outFilters = browser.getFilters(); } catch(BrokerException ex) { System.out.println("Failed to get filters."); } . . . //Various browse operations . . . //Close the queue browser try { browser.closeQueueBrowser(); } catch(BrokerException ex) { System.out.println("Failed to close client queue browser."); return; }
Viewing Queue Content
Viewing a Client's Own Queue Content
For a client to create a queue browser on its own queue and browse documents, follow these steps.
1 Create a queue browser using the BrokerClient.createClientQueueBrowser() method. This will create a queue browser on the client's queue.
Note: This mode of operation does not require a client queue to be locked; therefore the client queue content can undergo changes while the queue browser is open.
2 Set a filter or filters, if needed. Note that once a filter is set for the queue browser, all browse operations will only operate on documents that pass through the filters. See “Filters on a Queue Browser” on page 154 for instructions.
158 webMethods Broker Administration Java API Programmer’s Guide Version 8.2
11 Queue Browser
3 Use browseEvents to view the content of the queue. See “BrokerQueueBrowser and BrokerClientQueueBrowser” on page 146 for instructions.
The following example illustrates how to examine one's own queue content:
BrokerClient client = null; BrokerAdminClient admin = null; BrokerQueueBrowser browser = null; BrokerEvent[] events = null; int max_events = 100;//Maximum number of documents to be browsed int msecs = 30000; //Timeout for the browse operation //Create a Broker client try { client = new BrokerClient(broker_host, broker_name, client_id, client_group, "QueueBrowser - SELF", null); } catch(BrokerException ex) { System.out.println("Failed to create client."); return; } . . . //Create a queue browser try { browser = client.createClientQueueBrowser(); } catch(BrokerException ex) { System.out.println("Failed to create client queue browser."); return; } . . . //Browse operation try { events = browser.browseEvents( max_events, msecs); } catch(BrokerException ex) { System.out.println("Failed to complete browse operation."); return; } . . . //Various browse operations . . . //Close the queue browser try { browser.closeQueueBrowser(); } catch(BrokerException ex) { System.out.println("Failed to close queue browser."); return; }
Administratively Viewing Contents of an Unlocked Client Queue
For an administrative client to examine client queue content in an unlocked mode, follow these steps.
webMethods Broker Administration Java API Programmer’s Guide Version 8.2 159
11 Queue Browser
1 Create a queue browser in an unlocked mode using the BrokerAdminClient.createClientQueueBrowser(String client_id) method. This will create a queue browser on the specified client's queue.
Note: This mode of operation does not require a client queue to be locked; therefore the client queue content can undergo changes while the queue browser is open.
2 Set a filter or filters, if needed. It is important to note that once a filter is set for the queue browser, all browse operations will consider only documents that pass the filters. See “Filters on a Queue Browser” on page 154 for instructions.
3 Use browseEvents to view the content of the queue. See “BrokerLockedQueueBrowser and BrokerLockedClientQueueBrowser” on page 147 for instructions.
The following example illustrates how to examine a client queue in unlocked mode:
BrokerClient client = null; BrokerAdminClient admin = null; BrokerQueueBrowser browser = null; BrokerEvent[] events = null; int max_events = 100;//Maximum number of documents to be browsed int msecs = 30000; //Timeout for the browse operation //Create a Broker client try { client = new BrokerClient(broker_host, broker_name, client_id, client_group, "QueueBrowser ", null); } catch(BrokerException ex) { System.out.println("Failed to create client."); return; } //Create a Broker admin client try { admin = new BrokerAdminClient(broker_host, broker_name, null, "admin", "QueueBrowser-UNLOCKED", null); } catch(BrokerException ex) { System.out.println("Failed to create admin client."); return; } . . . //Create a queue browser in unlocked mode try { browser = admin.createClientQueueBrowser(client.getId()); } catch(BrokerException ex) { System.out.println("Failed to create client queue browser."); return; } . . .
160 webMethods Broker Administration Java API Programmer’s Guide Version 8.2
11 Queue Browser
//Browse operation try { events = browser.browseEvents(max_events, msecs); } catch(BrokerException ex) { System.out.println("Failed to complete browse operation."); return; } . . . //Various browse operations . . . //Close the queue browser try { browser.closeQueueBrowser(); } catch(BrokerException ex) { System.out.println("Failed to close queue browser."); return; }
Administratively Viewing Contents of a Locked Client Queue
For an administrative client to create a queue browser and examine client queue content in a locked mode, follow these steps.
1 Create a queue browser in locked mode using the BrokerAdminClient.createLockedClientQueueBrowser(String client_id) method. This will acquire a client queue lock to prevent further changes to the client queue. Note that even though the target client queue is locked, the Broker will continue to queue incoming documents according to the client's subscription. “Acquiring a Queue Lock” on page 153 for instructions.
2 Set a filter or filters, if needed. It is important to note that once a filter is set for the queue browser, all browse operations will consider only documents that pass the filters. See “Filters on a Queue Browser” on page 154 for instructions.
3 Use browseEvents to view the content of the queue. See “BrokerQueueBrowser and BrokerClientQueueBrowser” on page 146 for instructions.
The following example illustrates how to examine a client queue in LOCKED mode:
BrokerClient client = null; BrokerAdminClient admin = null; BrokerLockedQueueBrowser browser = null; BrokerEvent[] events = null; int max_events = 100;//Maximum number of documents to be browsed int msecs = 30000; //Timeout for the browse operation //Create a Broker client try { client = new BrokerClient(broker_host, broker_name, client_id, client_group, "QueueBrowser", null); } catch(BrokerException ex) {
webMethods Broker Administration Java API Programmer’s Guide Version 8.2 161
11 Queue Browser
System.out.println("Failed to create client."); return; } //Create a Broker admin client try { admin = new BrokerAdminClient(broker_host, broker_name, null, "admin", "QueueBrowser-LOCKED", null); } catch(BrokerException ex) { System.out.println("Failed to create admin client."); return; } . . . //Create a locked queue browser try { browser = admin.createLockedClientQueueBrowser(client.getId()); } catch(BrokerException ex) { System.out.println("Failed to create locked client queue browser."); return; } . . . //Browse operation try { events = browser.browseEvents(max_events, msecs); } catch(BrokerException ex) { System.out.println("Failed to complete browse operation."); return; } . . . //Various browse operations . . . //Close the queue browser try { browser.closeQueueBrowser(); } catch(BrokerException ex) { System.out.println("Failed to close queue browser."); return; }
Administratively Viewing Contents of an Unlocked Forwarding Queue
For an administrative client to examine forwarding queue content in an unlocked mode, follow these steps.
1 Create a queue browser in an unlocked mode using the BrokerAdminClient.createForwardQueueBrowser(String remote_broker_name) method. This will create a queue browser on the forwarding queue for the specified remote Broker.
String remote_broker_name: Name of the remote Broker.
162 webMethods Broker Administration Java API Programmer’s Guide Version 8.2
11 Queue Browser
Note: This mode of operation does not require a forwarding queue to be locked; therefore the forwarding queue content can undergo changes while the queue browser is open.
2 Set a filter or filters, if needed. Note that once a filter is set for the queue browser, all browse operations will only operate on documents that pass through the filters. See “Filters on a Queue Browser” on page 154 for instructions.
3 Use browseEvents to view the content of the queue. See “BrokerQueueBrowser and BrokerClientQueueBrowser” on page 146 for instructions.
The following example illustrates how to examine a forward queue in unlocked mode:
BrokerAdminClient admin = null; BrokerQueueBrowser browser = null; BrokerEvent[] events = null; int max_events = 100;//Maximum number of documents to be browsed int msecs = 30000; //Timeout for the browse operation //Create a Broker admin client try { admin = new BrokerAdminClient(broker_host, broker_name, null, "admin", "QueueBrowser-UNLOCKED", null); } catch(BrokerException ex) { System.out.println("Failed to create admin client."); return; } . . . //Create a queue browser in unlocked mode try { browser = admin.createForwardQueueBrowser(remote_broker_name); } catch(BrokerException ex) { System.out.println("Failed to create forward queue browser."); return; } . . . //Browse operation try { events = browser.browseEvents(max_events, msecs); } catch(BrokerException ex) { System.out.println("Failed to complete browse operation."); return; } . . . //Various browse operations . . . //Close the queue browser try { browser.closeQueueBrowser(); } catch(BrokerException ex) {
webMethods Broker Administration Java API Programmer’s Guide Version 8.2 163
11 Queue Browser
System.out.println("Failed to close queue browser."); return; }
Administratively Viewing Contents of a Locked Forwarding Queue
For an administrative client to create a queue browser and examine forward queue content in a locked mode, follow these steps.
1 Create a queue browser in locked mode using the BrokerAdminClient.createLockedForwardQueueBrowser(String remote_broker_name) method. This will acquire a queue lock to prevent further changes to the forward queue. Note that even though the target queue is locked, the Broker will continue to queue incoming documents according to the remote Broker's subscription. “Acquiring a Queue Lock” on page 153 for instructions.
2 Set a filter or filters, if needed. Note that once a filter is set for the queue browser, all browse operations will only operate on documents that pass through the filters. See “Filters on a Queue Browser” on page 154 for instructions.
3 Use browseEvents to view the content of the queue. See “BrokerQueueBrowser and BrokerClientQueueBrowser” on page 146 for instructions.
The following example illustrates how to examine a forwarding queue in LOCKED mode:
BrokerAdminClient admin = null; BrokerLockedQueueBrowser browser = null; BrokerEvent[] events = null; int max_events = 100;//Maximum number of documents to be browsed int msecs = 30000; //Timeout for the browse operation //Create a Broker admin client try { admin = new BrokerAdminClient(broker_host, broker_name, null, "admin", "QueueBrowser-LOCKED", null); } catch(BrokerException ex) { System.out.println("Failed to create admin client."); return; } . . . //Create a locked queue browser on remote Broker try { browser = admin.createLockedForwardQueueBrowser(remote_broker_name); } catch(BrokerException ex) { System.out.println("Failed to create locked forward queue browser."); return; } . . . //Browse operation try {
164 webMethods Broker Administration Java API Programmer’s Guide Version 8.2
11 Queue Browser
events = browser.browseEvents(max_events, msecs); } catch(BrokerException ex) { System.out.println("Failed to complete browse operation."); return; } . . . //Various browse operations . . . //Close the queue browser try { browser.closeQueueBrowser(); } catch(BrokerException ex) { System.out.println("Failed to close locked queue browser."); return; }
Identifying "Unacknowledged" Documents
A queue browse operation may return documents including those that are retrieved but not yet acknowledged. These documents are "unacknowledged" or "unacked" documents. The document acknowledgment status information can be retrieved from the returned BrokerEvent object using the following methods.
Use the BrokerEvent.getRetrievedStatus() method to check whether the document is an unacknowledged or not. If the document is unacked, this method returns "true".
If the document is unacked, use the BrokerEvent.getRetrievedSessionId() method to get information on the client session that retrieved this document.
For more information about BrokerEvent, see the webMethods Broker Client Java API Programmer’s Guide.
The following example illustrates how to examine an "unack" status on documents returned from a browse operation:
BrokerAdminClient admin = null; BrokerLockedQueueBrowser browser = null; //Create a Broker admin client try { admin = new BrokerAdminClient(broker_host, broker_name, null, "admin", "QueueBrowser", null); } catch(BrokerException ex) { System.out.println("Failed to create admin client."); return; } . . . //Create a queue browser .... . . . //Browse operation
webMethods Broker Administration Java API Programmer’s Guide Version 8.2 165
11 Queue Browser
try { events = browser.browseEvents(max_events, msecs); } catch(BrokerException ex) { System.out.println("Failed to complete browse operation."); return; } //Check unacked status try { for (int i=0; i< events.length; i++) { if (events[i].getRetrievedStatus()) { System.out.println("Event["+i+"] - "+events[i].getTypeName() "+
"has been retrieved by client session id "+ events[i].getRetrievedSessionId());
} else { System.out.println("Event["+i+"] - "+events[i].getTypeName() "+
" is available"); } } } catch(BrokerException ex) { System.out.println("Failed to complete ack status check on browse result."); return; } . . . //Various browse operations . . . //Close the queue browser try { browser.closeQueueBrowser(); } catch(BrokerException ex) { System.out.println("Failed to close queue browser."); return; }
Rearranging Queue Content
Rearranging queue content is possible only from a BrokerLockedQueueBrowser object.
Modifying Documents
Use the modifyEvents method to modify one or more documents on the target queue. A modify operation is equivalent to an "in-place replacement" of documents. You can only perform a modify operation from a BrokerLockedQueueBrowser object. Documents with "unack" status cannot be modified. The replacement document should match the storage type of the document that is being replaced.
The following example illustrates how to modify queue documents:
BrokerAdminClient admin = null; BrokerLockedQueueBrowser browser = null; BrokerEvent[] events = null; //Create a Broker admin client
166 webMethods Broker Administration Java API Programmer’s Guide Version 8.2
11 Queue Browser
try { admin = new BrokerAdminClient(broker_host, broker_name, null, "admin", "QueueBrowser-LOCKED", null); } catch(BrokerException ex) { System.out.println("Failed to create admin client."); return; } . . . //Create a locked queue browser on Broker client queue or forwarding queue for a remote Broker ... ... //Set cursor position to head try { browser.setPosition(0); } catch(BrokerException ex) { System.out.println("Failed to complete setPosition operation."); return; } . . . //Browse operation try { events = browser.browseEvents(2, 10000); } catch(BrokerException ex) { System.out.println("Failed to complete browse operation."); return; } //Swap events in position 0 and 1 try { long seqn[] = new long[2]; BrokerEvent[] new_events = new BrokerEvent[2]; seqn[0] = events[0].getReceiptSequenceNumber(); seqn[1] = events[1].getReceiptSequenceNumber(); new_events[0] = events[1]; new_events[1] = events[0]; browser.modifyEvents(seqn, new_events); } catch(BrokerException ex) { System.out.println("Failed to complete modify operation."); return; } . . . //Various browse operations . . . //Close the queue browser try { browser.closeQueueBrowser(); } catch(BrokerException ex) { System.out.println("Failed to close queue browser."); return; }
webMethods Broker Administration Java API Programmer’s Guide Version 8.2 167
11 Queue Browser
Inserting Documents
Use the BrokerLockedQueueBrowser.insertEventsAtHead method or insertEventsAtTail to insert one or more documents into the target queue.
The following example illustrates how to invoke the insertEvents method:
BrokerAdminClient admin = null; BrokerLockedQueueBrowser browser = null; BrokerEvent[] events = null; //Create a Broker admin client try { admin = new BrokerAdminClient(broker_host, broker_name, null, "admin", "QueueBrowser-LOCKED", null); } catch(BrokerException ex) { System.out.println("Failed to create admin client."); return; } . . . //Create a locked queue browser .... //Browse operation try { events = new BrokerEvent[2];
events[0] = new BrokerEvent(client, "API::Test") events[1] = new BrokerEvent(client, "API::Test")
//Populate event fields . . . } catch(BrokerException ex) { System.out.println("Failed to create new events."); return; } //Insert at head operation try { browser.insertEventsAtHead(events); } catch(BrokerException ex) { System.out.println("Failed to complete insert at head operation."); return; } //Insert at tail operation try { browser.insertEventsAtTail( events); } catch(BrokerException ex) { System.out.println("Failed to complete insert at tail operation."); return; } . . . //Various browse operations . . .
168 webMethods Broker Administration Java API Programmer’s Guide Version 8.2
11 Queue Browser
//Close the queue browser try { browser.closeQueueBrowser(); } catch(BrokerException ex) { System.out.println("Failed to close queue browser."); return; }
Deleting Documents
Use the BrokerLockedQueueBrowser.deleteEvents method to remove one or more documents from the queue. In order to use this method, you must know the receipt sequence numbers of the documents that you are trying to delete. The receipt sequence number of a document is unique and is assigned when the document is placed in the queue.
You can use the BrokerEvent.getReceiptSequenceNumber method to access the receipt sequence number of a document. Documents with an "unacked" status can also be deleted using this API. For more information, see “Identifying "Unacknowledged" Documents” on page 165.
The following example illustrates how to delete client queue documents:
BrokerAdminClient admin = null; BrokerLockedQueueBrowser = null; BrokerEvent[] events = null; //Create a Broker admin client try { admin = new BrokerAdminClient(broker_host, broker_name, null, "admin", "QueueBrowser-LOCKED", null); } catch(BrokerException ex) { System.out.println("Failed to create admin client."); return; } . . . //Create a locked queue browser ... //Browse operation try { events = browser.browseEvents(max_events, msecs); } catch(BrokerException ex) { System.out.println("Failed to complete browse operation."); return; } //Delete operation try { long seqn[] = new long[events.length]; for (int i = 0; i < events.length; ++i) { seqn[i] = events[i].getReceiptSequenceNumber();
webMethods Broker Administration Java API Programmer’s Guide Version 8.2 169
11 Queue Browser
} browser.deleteEvents( seqn); } catch(BrokerException ex) { System.out.println("Failed to complete delete operation."); return; } . . . //Various browse operations . . . //Close the queue browser try { browser.closeQueueBrowser(); } catch(BrokerException ex) { System.out.println("Failed to close client queue browser."); return; }
Unblocking the Forwarding Queue in a Territory or Cluster
If you observe that an internal event in the forwarding queue for a remote Broker is blocking the queue and not allowing events to flow across, you must delete and recreate the remote Broker. If the Broker belongs to a territory or cluster, force the Broker to leave and then rejoin the territory or cluster.
When an internal event is blocking the forwarding queue, do the following to unblock the queue.
To unblock the forwarding queue in a territory or cluster
Note: While changing a territory configuration or cluster configuration, allow some time for metadata changes to completely propagate across the network.
1 Create a backup of all the regular events contained in all the forwarding queues by saving the events to an external file. For more information about viewing events, see “Viewing Queue Content” on page 158, and Administering webMethods Broker.
2 Make the Broker leave the territory, or cluster. For more information, see “Removing a Broker from a Territory” on page 95.
3 Rejoin the Broker to the territory, or cluster. For more information, see “Adding a Broker to an Existing Territory” on page 95.
4 Restore all the regular events to their respective forwarding queues. For more information, see “Inserting Documents” on page 168.
170 webMethods Broker Administration Java API Programmer’s Guide Version 8.2
11 Queue Browser
Unblocking the Forwarding Queue in a Territory Gateway or Cluster Gateway
If you observe that an internal event in the forwarding queue for a remote Broker is blocking the queue and not allowing events to flow across, you must delete and recreate the remote Broker. If the Broker belongs to a territory gateway or cluster gateway, delete and recreate the blocked-half of the gateway.
To unblock the forwarding queue in a territory gateway or cluster gateway
Note: While changing a territory gateway configuration or cluster gateway configuration, allow some time for metadata changes to completely propagate across the network.
1 Create a backup of all the regular events contained in all the forwarding queues by saving the events to an external file. For more information about viewing events, see “Viewing Queue Content” on page 158 and Administering webMethods Broker.
2 Save the gateway configuration. For more information about importing and exporting Broker metadata, see Administering webMethods Broker.
3 Delete the blocked-half of the gateway. For more information, see “Creating and Destroying Gateways” on page 98, and “Creating and Destroying Cluster Gateways” on page 109.
4 Reconfigure the gateway. For more information about importing and exporting Broker metadata, see Administering webMethods Broker.
5 Restore all the regular events to their respective forwarding queues. For more information, see “Inserting Documents” on page 168.
Note: Because a Broker in a territory or cluster can have multiple forwarding queues, the backup of the forwarding queue events must be restored (reinserted) in the correct forwarding queue.
webMethods Broker Administration Java API Programmer’s Guide Version 8.2 171
11 Queue Browser
172 webMethods Broker Administration Java API Programmer’s Guide Version 8.2
12 Java API Administration Reference
AccessControlList . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 175
BrokerAdminClient . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 180
BrokerAdminTypeDef . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 302
BrokerAuthInfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 315
BrokerChangeLockInfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 317
BrokerClientGroupInfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 318
BrokerClientInfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 320
BrokerClientQueueBrowser . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 323
BrokerClientQueueBrowserInfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 326
BrokerClientSession . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 327
BrokerClusterGatewayInfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 331
BrokerClusterInfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 333
BrokerCompleteBroker . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 334
BrokerCompleteClient . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 340
BrokerCompleteClientGroup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 345
BrokerCompleteCollection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 350
BrokerCompleteEventType . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 354
BrokerCompleteServer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 358
BrokerCompleteTerritory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 366
BrokerCompleteTerritoryGateway . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 369
BrokerFilterDescriptor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 374
BrokerForwardQueueBrowser . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 375
BrokerInfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 378
BrokerJoinFailureInfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 379
BrokerLockedClientQueueBrowser . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 380
BrokerLockedForwardQueueBrowser . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 383
BrokerLockedQueueBrowser . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 385
BrokerLogConfig . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 387
webMethods Broker Administration Java API Programmer’s Guide Version 8.2 173
12 Java API Administration Reference
BrokerLogConfigEntry . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 394
BrokerMonitorClient . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 395
BrokerProcessInfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 401
BrokerQueueBrowser . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 402
BrokerQueueBrowserInfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 405
BrokerServerClient . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 406
BrokerServerConnectionCallback . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 438
BrokerServerLogEntry . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 439
BrokerServerLogInfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 440
BrokerSetFailureInfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 440
BrokerSharedEventTypeInfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 441
BrokerSharedEventTypeRefuseUpdateInfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 443
BrokerSSLCertificate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 444
BrokerSSLConfig . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 446
BrokerSSLConfigV2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 447
BrokerSSLIdentity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 451
BrokerSSLStatus . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 452
BrokerTerritoryGatewayInfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 453
BrokerTerritoryInfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 456
BrokerTraceEvent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 457
174 webMethods Broker Administration Java API Programmer’s Guide Version 8.2
12 Java API Administration Reference
AccessControlList
class BrokerAccessControlList extends java.lang.Object
This class represents a list of distinguished names of trusted entities. It is used by Broker to represent the entities that are allowed administrative access. It is also used by client groups to represent the entities that may create or reconnect a Broker client that is associated with the client group.
The access list is actually composed of two lists. One list contains the distinguished names of entities who are allowed access. The other list contains the distinguished names of certificate issuers who are trusted.
Constructors
BrokerAccessControlList
BrokerAccessControlList()
Creates an empty access control list.
BrokerAccessControlList
BrokerAccessControlList( BrokerAccessControlList acl) throws BrokerException
This is a copy constructor.
Methods
getAuthNames
String[] getAuthNames()
Returns an array of strings containing the names of all certificate authenticators and allowed basic authentication aliases defined in this list.
getAuthNameState
boolean getAuthNameState String name) throws BrokerException
acl The access list to be copied.
Possible Exceptions Meaning
BrokerNullParameterException The acl parameter is null.
webMethods Broker Administration Java API Programmer’s Guide Version 8.2 175
12 Java API Administration Reference
Returns true if the specified authenticator or basic authentication aliasname is currently in the list.
See Also:
BrokerAccessControlList.setAuthNameState and BrokerAccessControlList.setAuthNameStates
getUserNames
String[] getUserNames()
Returns an array of strings containing all SSL and basic authentication user names in this list.
See Also:
BrokerAccessControlList.getUserNameState and BrokerAccessControlList.setUserNames
getUserNameState
boolean getUserNameState( String name) throws BrokerException
Returns true if the specified name is currently in the list.
See Also:
BrokerAccessControlList.setUserNameState and BrokerAccessControlList.setUserNameStates
setAuthNames
void setAuthNames( String names[]) throws BrokerException
name The distinguished name of a certificate authenticator or basic authentication alias whose state is to be returned.
Possible Exceptions Meaning
BrokerNullParameterException The name parameter is null.
name The SSL or basic authentication user name whose state is to be returned.
Possible Exceptions Meaning
BrokerNullParameterException The name parameter is null.
176 webMethods Broker Administration Java API Programmer’s Guide Version 8.2
12 Java API Administration Reference
Sets the list of names that are certificate authenticators or basic authentication aliases. Certificates issued by any of the listed SSL authenticators will be considered to be trusted.
See Also:
BrokerAccessControlList.getAuthNames and BrokerAccessControlList.setAuthNameState
setAuthNameState
void setAuthNameState( String name, Boolean is_allowed) throws BrokerException
If is_allowed is true and the name is not in this list, it will be added. If is_allowed is false and the name is found in this list, it is removed.
See Also:
BrokerAccessControlList.getAuthNameState and BrokerAccessControlList.setAuthNameStates
setAuthNameStates
void setUserNames( String names[]) throws BrokerException
names An array of strings, each containing the name of a certificate authorizing entity or basic authentication alias.
Possible Exceptions Meaning
BrokerInvalidNameException One or more of the names in the names array is invalid.
BrokerNullParameterException The names parameter is null or any of its entries is null.
BrokerBlankParameterException The names parameter is blank, or a name in the array is blank.
name The authenticator or basic authentication alias name to be set for this list.
is_allowed Determines whether the authorizer or basic authentication alias name is added or removed from the list.
Possible Exceptions Meaning
BrokerNullParameterException The name parameter is null.
BrokerBlankParameterException The name parameter is blank.
webMethods Broker Administration Java API Programmer’s Guide Version 8.2 177
12 Java API Administration Reference
If is_allowed is true and any of the names are not in this list, they will be added. If is_allowed is false, any of the names found in this list are removed.
See Also:
BrokerAccessControlList.getAuthNameState and BrokerAccessControlList.setAuthNameState
setUserNames
void setUserNames( String names[]) throws BrokerException
Sets the SSL and basic authentication user names for this list. All previously existing SSL and basic authentication user names in the list are replaced.
See Also:
BrokerAccessControlList.getUserNameState and BrokerAccessControlList.setUserNameState
setUserNameState
void setUserNameState( String name, Boolean is_allowed) throws BrokerException
name The authenticator or basic authentication alias name to be set for this list.
is_allowed Determines whether the authenticator or basic authentication alias names are to be added or removed from the list.
Possible Exceptions Meaning
BrokerNullParameterException The names parameter is null or an entry it contains is null.
BrokerBlankParameterException The names parameter is blank, or a name in the array is blank.
names The SSL and basic authentication user names to be set for this list.
Possible Exceptions Meaning
BrokerNullParameterException The names parameter is null or any of its entries is null.
BrokerBlankParameterException The names parameter is blank, or a name in the array is blank.
178 webMethods Broker Administration Java API Programmer’s Guide Version 8.2
12 Java API Administration Reference
If is_allowed is true and the name is not in this list, it will be added. If is_allowed is false and the name is found in this list, it will be removed.
See Also:
BrokerAccessControlList.getUserNames, BrokerAccessControlList.getUserNameState, BrokerAccessControlList.setUserNameState, and BrokerAccessControlList.setUserNameStates
setUserNameStates
void setNameStates( String names[] boolean is_allowed) throws BrokerException
If is_allowed is true and any of the names are not in this list, they will be added. If is_allowed is false, any of the names found in this list are removed.
See Also:
BrokerAccessControlList.getUserNameState, BrokerAccessControlList.setUserNames, and BrokerAccessControlList.setUserNameState.
toString
String toString()
name The SSL or basic authentication user name to be set for this list.
is_allowed Determines whether the SSL or basic authentication user name is to be added or removed from the list.
Possible Exceptions Meaning
BrokerNullParameterException The name parameter is null.
BrokerBlankParameterException The names parameter is blank, or a name in the array is blank.
name The SSL and basic authentication user names to be set for this list.
is_allowed Determines whether the SSL and basic authentication user names are to be added or removed from the list.
Possible Exceptions Meaning
BrokerNullParameterException The names parameter is null or an entry it contains is null.
BrokerBlankParameterException The names parameter is blank, or a name in the array is blank.
webMethods Broker Administration Java API Programmer’s Guide Version 8.2 179
12 Java API Administration Reference
Returns a string containing the BrokerAccessControlList information in a human-readable format.
toString
String toString( int indent_level, String name)
Converts the access control list contained in this object into a string format that may be saved to a file.
BrokerAdminClient
class BrokerAdminClient extends COM.activesw.aweb.client.BrokerClient
This class represents a connection between an administrative client application and a Broker. This class provides methods for obtaining and setting the various administrative features of Brokers, Broker clients, and client groups.
The BrokerAdminClient class extends the BrokerClient class, described in the webMethods Broker Client Java API Programmer’s Guide, and therefore it has access to all of the BrokerClient methods.
Constants
LIFECYCLE_DESTROY_ON_DISCONNECT
LIFECYCLE_EXPLICIT_DESTROY
AUTH_TYPE_NONE
AUTH_TYPE_SSL
Constructor
BrokerAdminClient
BrokerAdminClient( String broker_host, String broker_name, String client_id, String client_group,
indent_level The number of 4-character spaces to use for indentation.
name An optional name for the access list. Can be set to null.
180 webMethods Broker Administration Java API Programmer’s Guide Version 8.2
12 Java API Administration Reference
String app_name, BrokerConnectionDescriptor desc) throws BrokerException
Creates a BrokerAdminClient object that is identical to a BrokerClient, except that it may use all of the special administration methods. The client is created with an empty event queue and no event subscriptions.
The application is responsible for invoking either the BrokerClient.disconnect or BrokerClient.destroy method, described in the webMethods Broker Client Java API Programmer’s Guide, when the BrokerAdminClient is no longer needed.
broker_host The name of the host where the Broker is running 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.
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 the webMethods Broker Client Java API Programmer’s Guide for more information on client identifiers.
client_group The name of the client group for the new Broker client. Client groups are discussed in Administering webMethods Broker.
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 may be shared with other Broker clients.
Possible Exceptions Meaning
BrokerClientExistsException Another Broker client is already using the specified client_id.
BrokerClientQueueBrowserException An operation pertaining to the creation or access of a client 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 administrative queue browser.
webMethods Broker Administration Java API Programmer’s Guide Version 8.2 181
12 Java API Administration Reference
See Also:
BrokerClient.disconnect, BrokerClient.destroy, BrokerAdminClient.newOrReconnectAdmin, and BrokerAdminClient.reconnectAdmin.
Methods
abort Methods
abortForced
void abortForced(long tx_id) throws BrokerException;
Forcibly terminates a transaction.
BrokerQueueBrowserException An operation pertaining to the creation or access of a client queue or forwarding 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 administrative queue browser.
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_group, or app_name parameter is null.
BrokerUnknownBrokerNameException The specified broker_name does not exist. If broker_name was null, then there is no default Broker.
BrokerUnknownClientGroupException The specified client_group does not exist on the Broker.
tx_id The Broker transaction context to abort.
Possible Exceptions Meaning
182 webMethods Broker Administration Java API Programmer’s Guide Version 8.2
12 Java API Administration Reference
abortForced
void abortForced(long tx_ids[]) throws BrokerException;
Forcibly terminates a list of transactions.
acquire Method
acquireChangeLock
BrokerChangeLockInfo acquireChangeLock() throws BrokerException
Returns a BrokerChangeLockInfo object for the Broker to which this client is connected. The use of this method allows cooperating client applications to avoid race conditions when updating the same Broker.
If a different client has already acquired a lock to this client's Broker, the acquired variable will be set to 0 (false) and the client_id, session_id will be set to the client and session holding the lock. The lock_time variable will contain the date and time when the lock was acquired.
If your client successfully acquires a lock on its Broker, the acquired variables will be set to 1 (true), client_id and lock_time will be set to null, and session_id will be set to zero.
It is safe to call this method again after acquiring the lock.
Exception Description
BrokerInvalidClientException The client has been destroyed or disconnected
BrokerInvalidTxException The transaction does not exist or the transaction state does not allow it to be aborted.
BrokerNoPermissionException The client does not have sufficient permissions.
tx_id A list of Broker transaction contexts to abort.
Exception Description
BrokerInvalidClientException The client has been destroyed or disconnected
BrokerNullParameterException tx_ids is null.
BrokerInvalidTxException One or more transactions do not exist or the transaction state does not allow it to be aborted.
BrokerNoPermissionException The BrokerAdminClient does not have necessary permissions on the Broker.
webMethods Broker Administration Java API Programmer’s Guide Version 8.2 183
12 Java API Administration Reference
See Also:
BrokerAdminClient.releaseChangeLock
add Method
addBrokerToCluster
BrokerJoinFailureInfo addBrokerToCluster( String broker_host, String broker_name) throws BrokerException
Causes this client's Broker join the cluster of the Broker with the specified broker_name that is running on broker_host. If the join operation is successful, a null value is returned. Otherwise, a BrokerJoinFailureInfo object will be returned that describes the client groups and event types defined for this Broker that conflict with the cluster's definitions.
For more information on the concept of clusters, see Administering webMethods Broker.
Possible Exceptions Meaning
BrokerIncompatibleVersionException The Broker Server does not support this operation.
BrokerInvalidClientException The BrokerAdminClient has been destroyed or disconnected.
broker_host The Broker host where broker_name is located. 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 whose cluster this Broker must join. This parameter may not be null.
Possible Exceptions Meaning
BrokerHostNotFoundException The specified broker_host does not exist.
BrokerInClusterException This client's Broker is already a member of a cluster.
BrokerInvalidClientException The BrokerAdminClient has been destroyed or disconnected.
BrokerNoPermissionException The BrokerAdminClient does not have permission to modify the Broker's properties or the Broker is not licensed for Broker interconnection.
BrokerNotInClusterException The Broker specified by broker_name is not a member of a cluster.
184 webMethods Broker Administration Java API Programmer’s Guide Version 8.2
12 Java API Administration Reference
See Also:
BrokerAdminClient.createCluster, BrokerAdminClient.getBrokersInCluster, BrokerAdminClient.getClusterStats, BrokerAdminClient.leaveCluster, and BrokerAdminClient.removeBrokerFromCluster
check Methods
checkAndRestartForwarding
int checkAndRestartForwarding() throws BrokerException
Checks for inactivity and restarts forwarding documents on remote Brokers, where remote Brokers include territory and gateway Brokers. If the reconnection request was successful, the non-zero return value indicates the actual number of remote Broker connections that were restarted. If the reconnection request was unsuccessful or no reconnection was necessary, the return value is a zero.
checkAndRestartForwarding
int checkAndRestartForwarding(String remote_broker_name) throws BrokerException
Checks for inactivity and restarts forwarding documents for a specific remote Broker. This remote Broker can be a territory or gateway Broker. If the reconnection request to the specified Broker was successful, the return value is one. If the reconnection request to the specified Broker was unsuccessful or no reconnection was necessary, the return value is a zero.
BrokerNullParameterException The parameter broker_host or broker_name is null.
BrokerOutOfRangeException There is another Broker in the specified cluster with the same name.
BrokerSecurityException If the cluster requires SSL and the joining Broker does not support SSL.
BrokerUnknownBrokerNameException The specified broker_name does not exist on the specified broker_host.
BrokerSSLClusterException SSL connection error between Broker Servers.
Possible Exceptions Meaning
BrokerInvalidClientException The BrokerAdminClient is invalid.
BrokerNullParameterException The remote Broker name is null.
remote_broker_name The name of the specific remote Broker you wish to restart.
Possible Exceptions Meaning
webMethods Broker Administration Java API Programmer’s Guide Version 8.2 185
12 Java API Administration Reference
clear Method
clearClientQueueById
void clearQueue( String client_id) throws BrokerException
Clears all events in the queue for the client with the specified client_id.
You can obtain a list of client identifiers by invoking the one of the following methods:
getClientIds
getClientIdsByClientGroup
getClientIdsWhichAreSubscribed
Important! Use this method with care because it deletes events that have not yet been processed by the Broker client(s) using the queue.
See Also:
BrokerAdminClient.getClientStatsById
commit Methods
commitForced
void commitForced(long tx_id) throws BrokerException
Possible Exceptions Meaning
BrokerInvalidClientException The BrokerAdminClient is invalid.
BrokerNullParameterException The specified remote Broker name is null.
client_id A string containing the client identifier whose event queue is to be cleared.
Possible Exceptions Meaning
BrokerInvalidClientException The BrokerAdminClient has been destroyed or disconnected.
BrokerNoPermissionException Permission to delete the client's events was denied.
BrokerNullParameterException The client_id parameter is null.
BrokerUnknownClientIdException The specified client does not exist on the Broker.
186 webMethods Broker Administration Java API Programmer’s Guide Version 8.2
12 Java API Administration Reference
Forcibly commits a transaction.
commitForced
void commitForced( long tx_ids[]) throws BrokerException
Forcibly commits a list of transactions.
create Methods
createClient
void createClient( String client_id, String client_group, String app_name, String user_name, String authenticator_name, BrokerConnectionDescriptor desc) throws BrokerException
tx_id The Broker transaction context to commit.
Exception Description
BrokerInvalidClientException The BrokerAdminClient has been destroyed or disconnected.
BrokerInvalidTxException Transaction tx_id does not exist or the transaction state does not allow it to be committed.
BrokerNoPermissionException The BrokerAdminClient does not have necessary permissions on the Broker.
tx_ids A list of Broker transaction contexts to commit.
Exception Description
BrokerInvalidClientException The BrokerAdminClient has been destroyed or disconnected.
BrokerInvalidTxException One or more transactions do not exist or the transaction state does not allow it to be committed.
BrokerNoPermissionException The BrokerAdminClient does not have necessary permissions on the Broker.
client_id The client identifier. See the webMethods Broker Client Java API Programmer’s Guide for more information on client identifiers.
webMethods Broker Administration Java API Programmer’s Guide Version 8.2 187
12 Java API Administration Reference
Creates a new Broker client on the Broker to which this administrative client is connected. Since this method does not result in a connection being opened with the Broker for the newly created client, the Broker client's groups must have a life cycle of explicit-destroy.
If either user_name or authenticator_name is null, the client is created without an owner.
The only property of the BrokerConnectionDescriptor desc that affects this method is the shared state setting.
Note: For information on client group name and client identifier restrictions, see the webMethods Broker Client Java API Programmer’s Guide.
createClientGroup
void createClientGroup( String client_group_name, int life_cycle, int storage_type) throws BrokerException
client_group The name of the client group for the new Broker client. Client groups are discussed in Administering webMethods Broker.
app_name The name of the application that will contain the new Broker client.
desc The connection descriptor used to set state sharing for the client. If set to null, state sharing will be disabled.
user_name The user name of the entity creating the client.
authenticator_name The name of the authenticator that issued the certificate for user_name.
Possible Exceptions Meaning
BrokerClientExistsException Another Broker client is already using the specified client_id.
BrokerInvalidClientException The BrokerAdminClient has been destroyed or disconnected.
BrokerInvalidClientIdException The client_id contains invalid characters.
BrokerInvalidNameException The app_name parameter contains invalid characters.
BrokerNoPermissionException The client does not have permission to modify clients in the specified client group.
BrokerNullParameterException The client_id, client_group_name, or app_name parameter is null.
BrokerUnknownClientGroupException The specified client_group does not exist.
188 webMethods Broker Administration Java API Programmer’s Guide Version 8.2
12 Java API Administration Reference
Creates a new client group on the Broker, setting the life cycle and the storage type for the clients associated with the group.
Note: Once a client group has been created, the life cycle and storage type cannot be changed.
The types of event to which clients can subscribe, the events they may publish, and the group's access control list must all be set separately.
See Also:
BrokerAdminClient.getClientGroupNames, BrokerAdminClient.setClientGroupCanPublishList, BrokerAdminClient.setClientGroupCanSubscribeList, BrokerAdminClient.setClientGroupDescription, and BrokerAdminClient.setClientInfosetById
createClientQueueBrowser
BrokerClientQueueBrowser createClientQueueBrowser(String client_id) throws BrokerException
client_group_name The name of the client group to be created. See the webMethods Broker Client Java API Programmer’s Guide for details on group name restrictions.
life_cycle The life cycle of the clients associated with the group. Must be either LIFECYCLE_DESTROY_ON_DISCONNECT or LIFECYCLE_EXPLICIT_DESTROY.
storage_type The storage type of the event queue for clients associated with the group. Must be one of these values:
BrokerTypeDef.STORAGE_GUARANTEED
BrokerTypeDef.STORAGE_VOLATILE
Possible Exceptions Meaning
BrokerClientGroupExistsException A client group with the specified name already exists on the Broker.
BrokerInvalidClientException The BrokerAdminClient has been destroyed or disconnected.
BrokerInvalidClientGroupNameException The specified client group name is not valid.
BrokerNoPermissionException The client does not have permission create a client group.
BrokerNullParameterException The client_group_name parameter is null.
BrokerOutOfRangeException The life_cycle or storage_parameter parameter contains an invalid value.
webMethods Broker Administration Java API Programmer’s Guide Version 8.2 189
12 Java API Administration Reference
Create an administrative client queue browser on the specified client's queue so that the administrative client can browse a client queue without acquiring the client's queue lock. Returns a BrokerClientQueueBrowser object if successful, otherwise throws a BrokerException. See “Queue Browser” on page 139 for more information about queue browsers.
See Also:
BrokerAdminClient.createLockedClientQueueBrowser and BrokerAdminClient.getClientQueueBrowsers
createClientSubscriptionById
void createClientSubscriptionById( String client_id, BrokerSubscription sub) throws BrokerException
Registers a subscription for the Broker client with the specified client_id for all events which match the subscription sub. An exception will be thrown if the BrokerAdminClient does not have permission to modify the client's subscription list or if the Broker client does not have permission to subscribe to the event.
Note: If the subscription has already been registered for the specified Broker client, invoking this method will have no effect.
You can use the doesClientSubscriptionExistById method to test for existing subscriptions.
You can obtain a list of client identifiers by invoking any of the following methods:
getClientIds
getClientIdsByClientGroup
getClientIdsWhichAreSubscribed
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.
BrokerUnknownClientIdException The specified client ID does not exist on the Broker.
BrokerClientQueueBrowserException A client queue browser is already open on the client queue from the same session.
client_id The identifier of the Broker client for which the subscription is to be created.
sub The subscription to register for the Broker client, which specifies an event type name and a filter.
190 webMethods Broker Administration Java API Programmer’s Guide Version 8.2
12 Java API Administration Reference
See Also:
BrokerAdminClient.createClientSubscriptionsById, BrokerAdminClient.destroyClientSubscriptionById, BrokerAdminClient.destroyClientSubscriptionsById, BrokerAdminClient.doesClientSubscriptionExistById, and BrokerAdminClient.getClientSubscriptionsById
createClientSubscriptionsById
void createClientSubscriptionsById( String client_id, BrokerSubscription subs[]) throws BrokerException
Registers multiple subscriptions for the Broker client with the specified client_id. An exception will be thrown if the calling BrokerAdminClient does not have permission to modify the client's subscription list or if the Broker client does not have permission to subscribe to any of the events.
Note: Any subscription specified in subs that is invalid or has already been registered for the specified Broker client will be ignored. Invalid subscriptions will cause an exception to be thrown. In both cases, all valid subscriptions will still be registered.
You can use the doesClientSubscriptionExistById method to test for existing subscriptions.
You can obtain a list of client identifiers by invoking the one of the following methods:
getClientIds
Possible Exceptions Meaning
BrokerInvalidClientException The BrokerAdminClient has been destroyed or disconnected.
BrokerInvalidSubscriptionException The filter string in sub contains a parse error.
BrokerNoPermissionException The BrokerAdminClient does not have permission to modify the Broker client's subscription list or the Broker client is not allowed to subscribe to the event type.
BrokerNullParameterException The client_id, sub, or sub.event_type_name parameter is null.
BrokerUnknownClientIdException The specified client does not exist on the Broker.
BrokerUnknownEventTypeException The event type does not exist on the Broker.
client_id The identifier of the Broker client for which the subscription is to be created.
subs The array of subscriptions to register for the Broker client, with each element specifying an event type name and a filter.
webMethods Broker Administration Java API Programmer’s Guide Version 8.2 191
12 Java API Administration Reference
getClientIdsByClientGroup
getClientIdsWhichAreSubscribed
See Also:
BrokerAdminClient.createClientSubscriptionById, BrokerAdminClient.destroyClientSubscriptionById, BrokerAdminClient.destroyClientSubscriptionsById, BrokerAdminClient.doesClientSubscriptionExistById, and BrokerAdminClient.getClientSubscriptionsById
createCluster
void createCluster( String cluster_name) throws BrokerException
Creates a new cluster with this Broker as the first member in the cluster. No warning will be issued if a cluster already exists with the same name. For more information on the concept of clusters, see Administering webMethods Broker.
Possible Exceptions Meaning
BrokerInvalidClientException The BrokerAdminClient has been destroyed or disconnected.
BrokerInvalidSubscriptionException One or more of the filter strings in subs contains a parse error. All correctly formatted subscriptions are still registered.
BrokerNoPermissionException The BrokerAdminClient does not have permission to modify the Broker client's subscription list or the Broker client is not allowed to subscribe to at least one of the event types specified in subs.
BrokerNullParameterException The parameter client_id, subs, a member of the subs array, or the event_type_name within a subscription is null.
BrokerOutOfRangeException One of the elements in subs has a sub_id that is less that zero.
BrokerUnknownClientIdException The specified client does not exist on Broker.
BrokerUnknownEventTypeException The event type does not exist on the Broker.
cluster_name The name of the cluster to be created. See the webMethods Broker Client Java API Programmer’s Guide for details on cluster name restrictions.
Possible Exceptions Meaning
BrokerInClusterException The Broker is already a member of the specified cluster.
192 webMethods Broker Administration Java API Programmer’s Guide Version 8.2
12 Java API Administration Reference
See Also:
BrokerAdminClient.createClusterGateway, BrokerAdminClient.getBrokersInCluster, BrokerAdminClient.getClusterStats, BrokerAdminClient.addBrokerToCluster, BrokerAdminClient.leaveCluster, BrokerAdminClient.removeBrokerFromCluster, BrokerAdminClient.setClientGroupACL, and BrokerAdminClient.setEventTypesAndClientGroups
createClusterGateway
void createClusterGateway( String cluster_name, String broker_host, String broker_name, boolean isPrimary) throws BrokerException
Creates a cluster gateway to the specified cluster by having the current Broker communicate with the Broker specified by broker_host and broker_name. This will only create one half of the gateway.
In order to complete the cluster gateway, this method must be invoked on the other Broker that makes up the gateway. Until both Brokers have created their halves of the gateway, the gateway will remain in an incomplete state.
BrokerInvalidClientException The BrokerAdminClient has been destroyed or disconnected.
BrokerInvalidClusterNameException The cluster name specified is not valid.
BrokerNoPermissionException The BrokerAdminClient does not have permission to modify the Broker's properties or the Broker is not licensed for Broker interconnection.
BrokerNullParameterException The cluster_name parameter is null.
cluster_name The name of the cluster to which this gateway is being created.
broker_host The name of the remote host that is running the Broker which will act as the other end of the cluster gateway. 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 remote Broker that will act as the other end of the cluster gateway.
isPrimary The cluster gateway connection will be made primary if set to true.
Possible Exceptions Meaning
BrokerHostNotFoundException The specified broker_host does not exist.
Possible Exceptions Meaning
webMethods Broker Administration Java API Programmer’s Guide Version 8.2 193
12 Java API Administration Reference
See Also:
BrokerAdminClient.createCluster and BrokerAdminClient.destroyClusterGateway.
createForwardQueueBrowser
BrokerQueueBrowser createForwardQueueBrowser(java.lang.String remoteBroker) throws BrokerException
Create an administrative forwarding queue browser on the forwarding queue of the specified remote Broker so that the administrative client can browse the forwarding queue without acquiring the remote Broker's queue lock. Returns a BrokerQueueBrowser object if successful, otherwise throws a BrokerException. See “Queue Browser” on page 139 for more information about queue browsers.
BrokerInvalidClientException The BrokerAdminClient has been destroyed or disconnected.
BrokerNoPermissionException The BrokerAdminClient does not have permission to modify the Broker's properties or the Broker is not licensed for Broker interconnection.
BrokerNotInClusterException The Broker is not a member of a cluster.
BrokerNotRunningException A Broker Server could not be found on the broker_host.
BrokerNullParameterException The cluster_name, broker_host, or broker_name is null.
BrokerOutOfRangeException The cluster_name is already connected to the cluster of broker_host through some other gateway, or a primary gateway already exists to the specified cluster.
BrokerUnknownBrokerNameException If the specified Broker does not exist.
BrokerUnknownClusterException There is no gateway to the specified cluster from this Broker.
remoteBroker Name of the remote Broker whose forward queue browser you want to create.
Possible Exceptions Meaning
BrokerInvalidClientException The forwarding queue has been already destroyed or is disconnected.
BrokerUnknownClientIdException The forwarding queue for the remote Broker specified does not exist on Broker.
Possible Exceptions Meaning
194 webMethods Broker Administration Java API Programmer’s Guide Version 8.2
12 Java API Administration Reference
createLockedClientQueueBrowser
BrokerLockedClientQueueBrowser createClientQueueBrowser(String client_id) throws BrokerException
Create an administrative client queue browser on the specified client's queue in locked mode. In the locked browse mode the client queue is locked for the lifetime of the queue browser. Using this queue browser, you can browse queue contents, delete documents from queue, insert new documents in to the queue and modify (in-place update) documents in the queue. Returns a BrokerClientQueueBrowser object if successful, otherwise throws a BrokerException. See “Queue Browser” on page 139 for more information about queue browsers.
See Also:
BrokerAdminClient.createClientQueueBrowser and BrokerAdminClient.getClientQueueBrowsers
createLockedForwardQueueBrowser
BrokerLockedForwardQueueBrowser createForwardQueueBrowser(String remoteBroker) throws BrokerException
Create an administrative forward queue browser on the specified forwarding queue in locked mode. In the locked browse mode the forwarding queue is locked for the lifetime of the queue browser. Returns a BrokerLockedQueueBrowser object if successful, otherwise throws a BrokerException. See “Queue Browser” on page 139 for more information about queue browsers.
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.
BrokerUnknownClientIdException The specified client ID does not exist on the Broker.
BrokerClientQueueBrowserException A client queue browser is already open on the client queue from the same session.
Possible Exceptions Meaning
BrokerIncompatibleVersionException An attempt was made to create a queue browser on a pre-8.1 Broker Server, which does not support forwarding queue browsers.
BrokerInvalidClientException The client has been already destroyed or is disconnected.
webMethods Broker Administration Java API Programmer’s Guide Version 8.2 195
12 Java API Administration Reference
See Also:
BrokerAdminClient.createForwardQueueBrowser.
createTerritory
void createTerritory( String territory_name) throws BrokerException
Creates a new territory with this Broker as the first member in the territory. No warning will be issued if a territory already exists which has the same name. For more information on the concept of territories, see Administering webMethods Broker.
See Also:
BrokerAdminClient.createTerritoryGateway, BrokerAdminClient.getBrokersInTerritory, BrokerAdminClient.getTerritoryStats, BrokerAdminClient.joinTerritory, BrokerAdminClient.leaveTerritory, BrokerAdminClient.removeBrokerFromTerritory, BrokerAdminClient.setClientGroupACL, and BrokerAdminClient.setEventTypesAndClientGroups
BrokerQueueBrowserException The forwarding queue for the remote Broker specified does not exist on Broker.
BrokerQueueBrowserException A queue browser is already open on the forwarding queue from the same session.
territory_name The name of the territory name to be created. See the webMethods Broker Client Java API Programmer’s Guide for details on territory name restrictions.
Possible Exceptions Meaning
BrokerInTerritoryException The Broker is already a member of the specified territory.
BrokerInvalidClientException The BrokerAdminClient has been destroyed or disconnected.
BrokerInvalidTerritoryNameException The territory name specified is not valid.
BrokerNoPermissionException The BrokerAdminClient does not have permission to modify the Broker's properties or the Broker is not licensed for Broker interconnection.
BrokerNullParameterException The parameter territory_name is null.
BrokerSecurityException If the territory requires SSL and the joining Broker does not support SSL.
Possible Exceptions Meaning
196 webMethods Broker Administration Java API Programmer’s Guide Version 8.2
12 Java API Administration Reference
createTerritoryGateway
void createTerritoryGateway( String territory_name, String broker_host, String broker_name) throws BrokerException
Creates a gateway to the specified territory by having the current Broker communicate with the Broker specified by broker_host and broker_name. This will only create one half of the gateway.
In order to complete the gateway, this method must be invoked on the other Broker that makes up the gateway. Until both Brokers have created their halves of the gateway, the gateway will remain in an incomplete state.
See Also:
BrokerAdminClient.createTerritory and BrokerAdminClient.destroyTerritoryGateway
territory_name The name of the territory to which this gateway is being created.
broker_host The name of the remote host that is running the Broker which will act as the other end of the gateway. 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 remote Broker that will act as the other end of the gateway.
Possible Exceptions Meaning
BrokerHostNotFoundException The specified broker_host does not exist.
BrokerInvalidClientException The BrokerAdminClient has been destroyed or disconnected.
BrokerNoPermissionException The BrokerAdminClient does not have permission to modify the Broker's properties or the Broker is not licensed for Broker interconnection.
BrokerNotInTerritoryException The Broker is not a member of a territory.
BrokerNotRunningException A Broker Server could not be found on the broker_host.
BrokerNullParameterException The territory_name, broker_host, or broker_name is null.
BrokerOutOfRangeException The territory_name is already connected to the territory of broker_host through some other gateway.
BrokerUnknownTerritoryException There is no gateway to the specified territory from this Broker.
webMethods Broker Administration Java API Programmer’s Guide Version 8.2 197
12 Java API Administration Reference
delete Method
deleteLogEvents
int deleteLogEvents( int from_index, int num_events) throws BrokerException
Deletes one or more events from the Broker's log. The number of events being deleted is not guaranteed to be 'n_events'. Returns the number of events deleted.
In addition, any of the communications errors can occur.
destroy Methods
destroyBroker
void destroyBroker() throws BrokerException
Destroys the Broker to which this BrokerAdminClient is currently connected.
See Also:
BrokerServerClient.destroy
from_index events to be deleted starting from this index
num_events number of events to be deleted
Possible Exceptions Meaning
BrokerInvalidClientException The BrokerAdminClient has been destroyed or disconnected.
BrokerNullParameterException Events are null.
BrokerOutOfRangeException Index is less than zero.
Possible Exceptions Meaning
BrokerInTerritoryException The Broker is in a territory with at least one other Broker and must leave the territory before being destroyed.
BrokerInvalidClientException The BrokerServerClient has been destroyed or disconnected.
BrokerNoPermissionException Client does not have permission to destroy the Broker.
198 webMethods Broker Administration Java API Programmer’s Guide Version 8.2
12 Java API Administration Reference
destroyClientById
void destroyClientById( String client_id) throws BrokerException
Destroys the BrokerClient with the specified client_id, including the event queue, the list of subscriptions, and all other state allocated for the client in the Broker.
You can obtain a list of client identifiers by invoking the one of the following methods:
getClientIds
getClientIdsByClientGroup
getClientIdsWhichAreSubscribed
See Also:
BrokerAdminClient.BrokerAdminClient, BrokerAdminClient.disconnectClientById, BrokerAdminClient.disconnectClientSessionById, BrokerClient.destroy, and BrokerClient.disconnect
destroyClientGroup
void destroyClientGroup( String client_group_name, boolean reserved1) throws BrokerException
Destroys the specified client group. If any existing Broker clients belong to the group, a BrokerDependencyException exception will be thrown and the client group will not be destroyed.
You can use the getClientIdsByClientGroup method to obtain a list of any Broker clients currently belonging to a group.
client_id The identifier of the Broker client to be destroyed.
Possible Exceptions Meaning
BrokerInvalidClientException The BrokerAdminClient has been destroyed or disconnected.
BrokerNoPermissionException The BrokerAdminClient does not have permission to destroy the specified Broker client.
BrokerNullParameterException The parameter client_id is null.
BrokerUnknownClientIdException The specified client does not exist on the Broker.
client_group_name The name of the client group to be destroyed.
reserved1 Reserved for future. Must be set to false.
webMethods Broker Administration Java API Programmer’s Guide Version 8.2 199
12 Java API Administration Reference
See Also:
BrokerAdminClient.createClientGroup, BrokerAdminClient.getClientGroupNames, and BrokerAdminClient.getClientIdsByClientGroup
destroyClientSubscriptionById
void destroyClientSubscriptionById( String client_id, BrokerSubscription sub) throws BrokerException
Cancels the subscription with the matching event type and filter for the Broker client with the specified client_id. Only the event type name and filter, specified by sub, are used to match the subscription.
You can obtain a list of client identifiers by invoking the one of the following methods:
getClientIds
getClientIdsByClientGroup
getClientIdsWhichAreSubscribed
Possible Exceptions Meaning
BrokerDependencyException One or more Broker clients are members of the client group.
BrokerInvalidClientException The BrokerAdminClient has been destroyed or disconnected.
BrokerNoPermissionException The BrokerAdminClient does not have permission to destroy the client group.
BrokerNullParameterException The parameter client_group_name is null.
BrokerUnknownClientGroupException The specified client group does not exist on the Broker.
client_id The identifier of the Broker client for which the subscription is to be cancelled.
sub The subscription to be cancelled for the Broker client, which specifies an event type name and a filter. The filter field may be null and the sub_id field is ignored.
Possible Exceptions Meaning
BrokerInvalidClientException The BrokerAdminClient has been destroyed or disconnected.
BrokerInvalidSubscriptionException There is no matching subscription for the specified Broker client.
200 webMethods Broker Administration Java API Programmer’s Guide Version 8.2
12 Java API Administration Reference
See Also:
BrokerAdminClient.createClientSubscriptionById, BrokerAdminClient.createClientSubscriptionsById, BrokerAdminClient.destroyClientSubscriptionsById, BrokerAdminClient.doesClientSubscriptionExistById, and BrokerAdminClient.getClientSubscriptionsById
destroyClientSubscriptionsById
void destroyClientSubscriptionsById( String client_id, BrokerSubscription subs[]) throws BrokerException
Cancels multiple subscription for the Broker client with the specified client_id. Only the event type name and filter, specified in each element of the subs array, are used to match each subscription.
You can obtain a list of client identifiers by invoking the one of the following methods:
getClientIds
getClientIdsByClientGroup
getClientIdsWhichAreSubscribed
BrokerNoPermissionException The BrokerAdminClient does not have permission to modify the Broker client's subscription list.
BrokerNullParameterException The client_id, sub, or sub.event_type_name parameter is null.
BrokerUnknownClientIdException The specified client does not exist on the Broker.
client_id The identifier of the Broker client whose subscription are to be cancelled.
subs The array of subscriptions to be cancelled for the Broker client, with each element specifying an event type name and a filter. An element's filter field may be null and its sub_id field is ignored.
Possible Exceptions Meaning
BrokerInvalidClientException The BrokerAdminClient has been destroyed or disconnected.
Possible Exceptions Meaning
webMethods Broker Administration Java API Programmer’s Guide Version 8.2 201
12 Java API Administration Reference
See Also:
BrokerAdminClient.createClientSubscriptionById, BrokerAdminClient.createClientSubscriptionsById, BrokerAdminClient.destroyClientSubscriptionById, BrokerAdminClient.doesClientSubscriptionExistById, and BrokerAdminClient.getClientSubscriptionsById
destroyClusterGateway
void destroyClusterGateway( String cluster_name, String broker_name) throws BrokerException
Destroys one half of the gateway to the specified cluster.
This method will only destroy one half of the gateway. To completely remove the gateway, this method must be invoked on the other Broker that make up the gateway. Until that is done, the gateway on the other Broker will be in an incomplete state.
BrokerInvalidSubscriptionException There are no matching subscriptions for the specified Broker client for one or more of the specified subscriptions. If this exception is thrown, all matching subscriptions will still be destroyed.
BrokerNoPermissionException The BrokerAdminClient does not have permission to modify the Broker client's subscription list.
BrokerNullParameterException The client_id or subs, parameter is null, any element in subs is null, or any element's event_type_name field is null.
BrokerUnknownClientIdException The specified client does not exist on the Broker.
cluster_name The name of the cluster whose gateway is to be destroyed.
broker_name The name of the Broker belonging to the specified cluster to which the gateway is to be destroyed.
Possible Exceptions Meaning
BrokerInvalidClientException The BrokerAdminClient has been destroyed or disconnected.
BrokerNoPermissionException The BrokerAdminClient does not have permission to modify the Broker's properties.
BrokerNotInClusterException The Broker is not a member of a cluster.
Possible Exceptions Meaning
202 webMethods Broker Administration Java API Programmer’s Guide Version 8.2
12 Java API Administration Reference
See Also:
BrokerAdminClient.createCluster and BrokerAdminClient.createClusterGateway
destroyEventType
void destroyEventType( String event_type_name, boolean reserved1) throws BrokerException
Destroys the specified event type. If an existing Broker client subscription or client group uses the event type, a BrokerDependencyException exception will be thrown and the event type will not be destroyed.
You can use the following methods to determine which Broker clients or client groups are dependent on a particular event type:
getClientIdsWhichAreSubscribed
getClientGroupsWhichCanPublish
getClientGroupsWhichCanSubscribe
BrokerNullParameterException The cluster_name or broker_name parameter value is null.
BrokerUnknownClusterException There is no gateway connection to the specified cluster from this Broker.
event_type_name The name of the event type to be destroyed.
reserved1 Reserved for future. Must be set to false.
Possible Exceptions Meaning
BrokerDependencyException One or more client groups have can-publish or can-subscribe permission to the event type or the event type is specified in one or more Broker client subscriptions.
BrokerInvalidClientException The BrokerAdminClient has been destroyed or disconnected.
BrokerNoPermissionException The BrokerAdminClient does not have permission to destroy the event type.
BrokerNullParameterException The parameter event_type_name is null.
BrokerUnknownEventTypeException The event type does not exist on the Broker.
Possible Exceptions Meaning
webMethods Broker Administration Java API Programmer’s Guide Version 8.2 203
12 Java API Administration Reference
See Also:
BrokerAdminClient.destroyEventTypes, BrokerAdminClient.getEventAdminTypeDef, BrokerAdminClient.getEventAdminTypeDefs, BrokerAdminClient.setEventAdminTypeDef, and BrokerAdminClient.setEventAdminTypeDefs
destroyEventTypeInfoset
void destroyEventTypeInfoset( String event_type_name, String infoset_name) throws BrokerException
Destroys the specified infoset for the specified event type.
See Also:
BrokerAdminClient.destroyEventTypeInfosets, BrokerAdminClient.setEventTypeInfoset, BrokerAdminClient.setEventTypeInfosets as well as BrokerClient.getEventTypeInfoset, and BrokerClient.getEventTypeInfosets (described in the webMethods Broker Client Java API Programmer’s Guide)
destroyEventTypeInfosets
void destroyEventTypeInfosets( String event_type_name, String infoset_names[]) throws BrokerException
event_type_name The name of the event type whose specified infoset is to be destroyed.
infoset_name The name of the infoset to be destroyed.
Possible Exceptions Meaning
BrokerInvalidClientException The BrokerAdminClient has been destroyed or disconnected.
BrokerNoPermissionException The BrokerAdminClient does not have permission to destroy the event type infoset.
BrokerNullParameterException The parameter event_type_name or infoset_name is null.
BrokerUnknownEventTypeException The event type does not exist on the Broker.
BrokerUnknownInfosetException The infoset does not exist on the Broker.
event_type_name The name of the event type whose specified infosets are to be destroyed.
infoset_names The names of the infosets to be destroyed.
204 webMethods Broker Administration Java API Programmer’s Guide Version 8.2
12 Java API Administration Reference
Destroys the specified infosets for the specified event type. If infoset_names is null, all infosets for the specified event type will be destroyed.
Note: If an infoset contained in infoset_names cannot be found. it will be ignored.
See Also:
BrokerAdminClient.destroyEventTypeInfosets, BrokerAdminClient.setEventTypeInfoset, BrokerAdminClient.setEventTypeInfosets, BrokerClient.getEventTypeInfoset, and BrokerClient.getEventTypeInfosets
destroyEventTypes
void destroyEventTypes( String event_type_names[], boolean force_destroy) throws BrokerException
Destroys the specified event types. The force_destroy flag determines whether or not any currently existing Broker client subscription or client group that uses any of the event types will be affected.
Note: If an event type name contained in event_type_names cannot be found, it will be ignored.
You can use the following methods to determine which Broker clients or client groups are dependent on a particular event type:
getClientIdsWhichAreSubscribed
getClientGroupsWhichCanPublish
Possible Exceptions Meaning
BrokerInvalidClientException The BrokerAdminClient has been destroyed or disconnected.
BrokerNoPermissionException The BrokerAdminClient does not have permission to destroy the event type infoset.
BrokerNullParameterException The parameter event_type_name or any entry in infoset_names is null.
BrokerUnknownEventTypeException The event type does not exist on the Broker.
event_type_names An array of names of the event types to be destroyed.
force_destroy If set to true, any Broker client subscriptions using any of the event types are destroyed as are any can-publish or can-subscribe entries in any client groups. If set to false, an exception is raised if at least one event type is used in any subscription or client group.
webMethods Broker Administration Java API Programmer’s Guide Version 8.2 205
12 Java API Administration Reference
getClientGroupsWhichCanSubscribe
See Also:
BrokerAdminClient.destroyEventTypeInfosets, BrokerAdminClient.setEventTypeInfoset, BrokerAdminClient.setEventTypeInfosets, BrokerClient.getEventTypeInfoset, and BrokerClient.getEventTypeInfosets
destroyTerritoryGateway
void destroyTerritoryGateway( String territory_name) throws BrokerException
Destroys one half of the gateway to the specified territory.
This method will only destroy one half of the gateway. It must be invoked on each of the two Brokers that make up the gateway. Until that is done, the gateway on the other Broker will be in an incomplete state.the gateway will remain in an incomplete state.
Possible Exceptions Meaning
BrokerDependencyException The parameter force_destroy is false and any of the event_type_names is used by one or more Broker client subscriptions or by one or more client groups. If this exception is thrown, no event types will be destroyed.
BrokerInvalidClientException The BrokerAdminClient has been destroyed or disconnected.
BrokerNoPermissionException The BrokerAdminClient does not have permission to destroy the event types.
BrokerNullParameterException The parameter event_type_names is null or any of its elements is null.
territory_name The name of the territory whose gateway is to be destroyed.
Possible Exceptions Meaning
BrokerInvalidClientException The BrokerAdminClient has been destroyed or disconnected.
BrokerNoPermissionException The BrokerAdminClient does not have permission to modify the Broker's properties.
BrokerNotInTerritoryException The Broker is not a member of a territory.
BrokerNullParameterException The territory_name parameter is null.
BrokerUnknownTerritoryException There is no gateway to the specified territory from this Broker.
206 webMethods Broker Administration Java API Programmer’s Guide Version 8.2
12 Java API Administration Reference
See Also:
BrokerAdminClient.createTerritory and BrokerAdminClient.createTerritoryGateway
disconnect Methods
disconnectClientById
void disconnectClientById( String client_id) throws BrokerException
Closes all sessions for the specified Broker client. 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. Client groups are described in Administering webMethods Broker.
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.
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.
You can obtain a list of client identifiers by invoking the one of the following methods:
getClientIds
getClientIdsByClientGroup
getClientIdsWhichAreSubscribed
See Also:
BrokerAdminClient.destroyClientById and BrokerAdminClient.disconnectClientSessionById
client_id The identifier of the Broker client to be disconnected.
Possible Exceptions Meaning
BrokerInvalidClientException The BrokerAdminClient has been destroyed or disconnected.
BrokerNoPermissionException The BrokerAdminClient does not have permission to disconnect the Broker client.
BrokerNullParameterException The parameter client_id is null.
BrokerUnknownClientIdException The specified client does not exist on the Broker.
webMethods Broker Administration Java API Programmer’s Guide Version 8.2 207
12 Java API Administration Reference
disconnectClientSessionById
void disconnectClientSessionById( String client_id, int session_id) throws BrokerException
Disconnects the specified session for the Broker client. 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. Client groups are described in Administering webMethods Broker.
You can obtain a list of client identifiers by invoking the one of the following methods:
getClientIds
getClientIdsByClientGroup
getClientIdsWhichAreSubscribed
You can obtain a list of session identifiers how using one of the following methods:
getClientInfoById
getClientInfosById
See Also:
BrokerAdminClient.destroyClientById
does Method
doesClientSubscriptionExistById
boolean doesClientSubscriptionExistById( String client_id, String event_type_name, String filter) throws BrokerException
client_id The identifier of the Broker client.
session_id The identifier of the session to be disconnected.
Possible Exceptions Meaning
BrokerInvalidClientException The BrokerAdminClient has been destroyed or disconnected.
BrokerNoPermissionException The BrokerAdminClient does not have permission to disconnect the Broker client.
BrokerNullParameterException The client_id parameter is null.
BrokerUnknownClientIdException The specified client does not exist on the Broker.
BrokerUnknownSessionIdException The specified client session does not exist on the Broker.
208 webMethods Broker Administration Java API Programmer’s Guide Version 8.2
12 Java API Administration Reference
Returns true if a subscription with the specified event_type_name and filter exists for the client with the specified client_id. Otherwise, false is returned.
The filter parameter can be null if the subscription you wish to match was created without a filter.
You can obtain a list of client identifiers by invoking the one of the following methods:
getClientIds
getClientIdsByClientGroup
getClientIdsWhichAreSubscribed
See Also:
BrokerAdminClient.createClientSubscriptionById, BrokerAdminClient.createClientSubscriptionsById, BrokerAdminClient.destroyClientSubscriptionById, BrokerAdminClient.destroyClientSubscriptionsById, BrokerAdminClient.getClientGroupsWhichCanSubscribe, BrokerAdminClient.getClientIdsWhichAreSubscribed, and BrokerAdminClient.getClientSubscriptionsById
forget Methods
forgetForced
void forgetForced(long tx_id) throws BrokerException;
Forcibly purge a heuristic transaction.
client_id The identifier of the Broker client whose subscription is being tested.
event_type_name The event type name associated with the subscription being tested.
filter The filter associated with the subscription being tested. This parameter can be set to null.
Possible Exceptions Meaning
BrokerInvalidClientException The BrokerAdminClient has been destroyed or disconnected.
BrokerNoPermissionException The BrokerAdminClient does not have permission to read the Broker client's subscriptions.
BrokerNullParameterException The client_id or event_type_name parameter is null.
BrokerUnknownClientIdException The specified client does not exist on the Broker.
tx_id The Broker transaction context to purge.
webMethods Broker Administration Java API Programmer’s Guide Version 8.2 209
12 Java API Administration Reference
forgetForced
void forgetForced(long tx_ids[]) throws BrokerException;
Forcibly purge a list of heuristic transactions.
forgetForced
void forgetForced() throws BrokerException;
Forcibly purge all heuristic transactions.
get Methods
getActivityTraces
BrokerTraceEvent[] getActivityTraces( int seqn, int msecs) throws BrokerException
Exception Description
BrokerInvalidClientException The BrokerAdminClient has been destroyed or disconnected.
BrokerInvalidTxException The transaction does not exist.
BrokerNoPermissionException The BrokerAdminClient does not have necessary permissions on the Broker.
tx_ids A list of Broker transaction contexts to purge.
Exception Description
BrokerInvalidClientException The BrokerAdminClient has been destroyed or disconnected.
BrokerNullParameterException tx_ids is null.
BrokerNoPermissionException The BrokerAdminClient does not have necessary permissions on the Broker.
Exception Description
BrokerInvalidClientException The BrokerAdminClient has been destroyed or disconnected.
BrokerNoPermissionException The BrokerAdminClient does not have necessary permissions on the Broker.
210 webMethods Broker Administration Java API Programmer’s Guide Version 8.2
12 Java API Administration Reference
Returns an array of BrokerTraceEvent objects containing Broker activity traces. The first element contains a number that should be used to set seqn plus one for all subsequent calls.
Important! Only the last 100 activity traces are available through this method, so you should not rely on this method to provide complete trace information. If the Broker is exceptionally busy or if this method is called infrequently, trace information will be lost.
getAllClusterGateways
BrokerClusterGatewayInfo[] getAllClusterGateways() throws BrokerException
Returns all of the cluster gateways accessible from this Broker, through local gateways or gateways from other Brokers.
getAllQueueStats
public BrokerAllQueueStat[] getAllQueueStats() throws BrokerException
Returns a BrokerEvent object containing statistics for all clients.
seqn The index of the activity trace array to be returned. This should be set to 0 on the first invocation. For all subsequent invocations it should be set to one plus the value of the sequence number of the last element returned on the previous invocation.
msecs The number of milliseconds this method will wait for trace information to be returned. If set to -1, it will block indefinitely.
Possible Exceptions Meaning
BrokerInterruptedException This operation was interrupted before it could be completed.
BrokerInvalidClientException The BrokerAdminClient has been destroyed or disconnected.
BrokerNoPermissionException The BrokerAdminClient does not have permission to read the activity traces.
Possible Exceptions Meaning
BrokerInvalidClientException The BrokerAdminClient has been destroyed or disconnected.
BrokerNoPermissionException The BrokerAdminClient does not have permission to browse the Broker.
BrokerNotInClusterException The Broker is not a member of a cluster.
webMethods Broker Administration Java API Programmer’s Guide Version 8.2 211
12 Java API Administration Reference
The event returned by the BrokerAdminClient.getAllQueueStats method contains fields described in the following table.
Field Name Type Description
now BrokerDate Current time on the Broker host.
createTime BrokerDate Time when the client was created.
numEventsPublished int Number of events published by this client.
numEventsForwarded int Number of events forwarded by the forwarding queue for the remote Broker.
numEventsDelivered int Number of events delivered by this client.
numEventsReceived int Number of events received by the forwarding queue for the remote Broker.
numEventsQueued int Number of events queued for this client.
numEventsEnqueued int Number of events enqueued for the forwarding queue.
numEventsRetrieved int Number of events retrieved by this client.
lastEventPublishTime BrokerDate Time when last event was published by this client. A date and time value of zero indicates that the client has never published an event.
lastEventForwardTime BrokerDate Time when last event was forwarded by the forwarding queue. A date and time value of zero indicates that the forwarding queue has never forwarded an event.
lastEventDeliveryTime BrokerDate Time when last event was delivered by this client. A date and time value of zero indicates that the client has never delivered an event.
lastEventReceiveTime BrokerDate Time when last event was received by this forward queue. A date and time value of zero indicates that the forward queue has never received an event.
lastEventQueueTime BrokerDate Time when last event was queued for this client. A date and time value of zero indicates that the client has never queued an event.
lastEventRetrieveTime BrokerDate Time when last event was retrieved by this client. A date and time value of zero indicates that the client has never retrieved an event.
212 webMethods Broker Administration Java API Programmer’s Guide Version 8.2
12 Java API Administration Reference
getAllTerritoryGateways
BrokerTerritoryGatewayInfo[] getAllTerritoryGateways() throws BrokerException
Returns all of the territory gateways accessible from this Broker, through local gateways or gateways from other Brokers.
getBrokerDescription
String getBrokerDescription() throws BrokerException
Returns a string containing a description of the Broker to which this BrokerAdminClient is connected.
lastConnectTime BrokerDate Time when last session connected.
lastConnectSession int Session ID of the last connected session.
lastDisconnectTime BrokerDate Time when last session disconnected.
lastDisconnectSession int Session ID of the last disconnected session.
queueLength long Number of events in client queue.
queueByteSize long Number of bytes worth of events in client queue.
queueHighestLength long Highest value of queueLength.
queueHighestLengthTime BrokerDate Time when queueHighestLength was last set. A date and time value of zero indicates that the queueHighestLength has never been set.
Possible Exceptions Meaning
BrokerInvalidClientException The BrokerAdminClient has been destroyed or disconnected.
BrokerNoPermissionException The BrokerAdminClient does not have permission to browse the Broker.
BrokerNotInClusterException The Broker is not a member of a cluster.
Possible Exceptions Meaning
BrokerInvalidClientException The BrokerAdminClient has been destroyed or disconnected.
BrokerNoPermissionException The BrokerAdminClient does not have permission to browse the Broker.
BrokerNotInTerritoryException The Broker is not a member of a territory.
Field Name Type Description
webMethods Broker Administration Java API Programmer’s Guide Version 8.2 213
12 Java API Administration Reference
See Also:
BrokerAdminClient.setBrokerDescription
getBrokersInCluster
BrokerInfo[] getBrokersInCluster() throws BrokerException
Returns an array of BrokerInfo objects, one for each Broker in this Broker's cluster. This Broker will appear first in the list.
See Also:
BrokerAdminClient.createCluster, BrokerAdminClient.getClusterStats, BrokerAdminClient.addBrokerToCluster, BrokerAdminClient.leaveCluster, and BrokerAdminClient.removeBrokerFromCluster
getBrokersInTerritory
BrokerInfo[] getBrokersInTerritory() throws BrokerException
Returns an array of BrokerInfo objects, one for each Broker in this Broker's territory. This Broker will appear first in the list.
Possible Exceptions Meaning
BrokerInvalidClientException The BrokerAdminClient has been destroyed or disconnected.
Possible Exceptions Meaning
BrokerInvalidClientException The BrokerAdminClient has been destroyed or disconnected.
BrokerNoPermissionException The BrokerAdminClient does not have permission to read the Broker's properties.
BrokerNotInClusterException This Broker is not part of a cluster.
Possible Exceptions Meaning
BrokerInvalidClientException The BrokerAdminClient has been destroyed or disconnected.
BrokerNoPermissionException The BrokerAdminClient does not have permission to read the Broker's properties.
BrokerNotInTerritoryException This Broker is not part of a territory.
214 webMethods Broker Administration Java API Programmer’s Guide Version 8.2
12 Java API Administration Reference
See Also:
BrokerAdminClient.createTerritory, BrokerAdminClient.getTerritoryStats, BrokerAdminClient.joinTerritory, BrokerAdminClient.leaveTerritory, and BrokerAdminClient.removeBrokerFromTerritory
getBrokerStats
BrokerEvent getBrokerStats() throws BrokerException
Returns a BrokerEvent containing statistics about the Broker to which this BrokerAdminClient is connected. The following table shows the events returned by the BrokerAdminClient.getBrokerStats method.
Field Name Type Description
createTime BrokerDate The time the Broker was created.
eventLogLength long The number of events in the Broker log.
now BrokerDate Current time on the Broker host.
numClients int The number of clients on the Broker, including disconnected clients.
numEventTypes int The number of event types installed.
numEventsDelivered int The number of events delivered by all clients.
numEventPublished int The number of events published by all clients.
numEventsQueued int The number of events placed in client queues.
numTracesPublished int The number of trace events published by Broker.
retryQueueMaxPublishes int The maximum number of publishes.
retryQueueMaxEvents int The maximum number of events.
retryQueueNextOpsSequenceNum int Next operation sequence number.
retryQueueReservedGuaranteedEvents int The number of guaranteed events.
webMethods Broker Administration Java API Programmer’s Guide Version 8.2 215
12 Java API Administration Reference
See Also:
BrokerAdminClient.getClientGroupStats, BrokerAdminClient.getClientStatsById, and BrokerAdminClient.getEventTypeStats
retryQueueReservedGuaranteedPublishes int The number of guaranteed publishes.
retryQueueReservedTotalPublishes int The total number of reserved publishes.
retryQueueReservedVolatileEvents int The number of volatile events.
retryQueueReservedVolatilePublishes int The number of volatile publishes.
retryQueueCurrentEvents int The number of current events.
retryQueueCurrentPublishes int The number of current publishes.
traceLastEventEnqueueTime date The time when last event was enqueued.
traceNumEventsQueued int The number of events placed in the queue.
traceQueueByteSize long The number of bytes worth of events in the queue.
traceQueueHighestLength long The highest value of traceQueueLength.
traceQueueHighestLengthTime date The time when traceQueueHighestLength was last set. Forever (zero date and time) if an event was never queued.
traceQueueLength long The number of events in queue.
Possible Exceptions Meaning
BrokerInvalidClientException The BrokerAdminClient has been destroyed or disconnected.
BrokerNoPermissionException The BrokerAdminClient does not have permission to read the Broker's statistics.
Field Name Type Description
216 webMethods Broker Administration Java API Programmer’s Guide Version 8.2
12 Java API Administration Reference
getClientGroupACL
BrokerAccessControlList getClientGroupACL( String client_group_name) throws BrokerException
Returns an array of strings containing the distinguished names of entities that may create and use Broker clients that belong to the specified client group.
See AccessControlList for more information on the format of the returned object.
See Also:
BrokerAdminClient.setClientGroupACL
getClientGroupCanPublishList
String[] getClientGroupCanPublishList( String client_group_name) throws BrokerException
Returns an array of strings containing the event types that may be published or delivered by Broker clients that belong to the specified client group.
client_group_name The name of the client group whose access control list is to be returned.
Possible Exceptions Meaning
BrokerInvalidClientException The BrokerAdminClient has been destroyed or disconnected.
BrokerNoPermissionException The BrokerAdminClient does not have permission to read the client group's Access Control List.
BrokerNullParameterException The client_group_name parameter is null.
BrokerUnknownClientGroupException The specified client_group_name does not exist on the Broker.
client_group_name The name of the client group whose publish list is to be returned.
Possible Exceptions Meaning
BrokerInvalidClientException The BrokerAdminClient has been destroyed or disconnected.
BrokerNoPermissionException The BrokerAdminClient does not have permission to read the client group's can-publish list.
BrokerNullParameterException The client_group_name parameter is null.
BrokerUnknownClientGroupException The specified client_group_name does not exist on the Broker.
webMethods Broker Administration Java API Programmer’s Guide Version 8.2 217
12 Java API Administration Reference
See Also:
BrokerAdminClient.getClientGroupCanSubscribeList, BrokerAdminClient.setClientGroupCanPublishList, and BrokerAdminClient.setClientGroupCanSubscribeList
getClientGroupCanSubscribeList
String[] getClientGroupCanSubscribeList( String client_group_name) throws BrokerException
Returns an array of strings containing the event types that may be subscribed to, or which may be delivered to, Broker clients that belong to the specified client group.
See Also:
BrokerAdminClient.getClientGroupCanPublishList, BrokerAdminClient.setClientGroupCanPublishList, and BrokerAdminClient.setClientGroupCanSubscribeList
getClientGroupInfo
BrokerClientGroupInfo getClientGroupInfo( String client_group_name) throws BrokerException
Returns the client group's information.
See BrokerClientGroupInfo for more information on the format of the returned object.
client_group_name The name of the client group whose subscribe list is to be returned.
Possible Exceptions Meaning
BrokerInvalidClientException The BrokerAdminClient has been destroyed or disconnected.
BrokerNoPermissionException The BrokerAdminClient does not have permission to read the client group's can-subscribe list.
BrokerNullParameterException The client_group_name parameter is null.
BrokerUnknownClientGroupException The specified client_group_name does not exist on the Broker.
client_group_name The name of the client group whose information is to be returned.
Possible Exceptions Meaning
BrokerInvalidClientException The BrokerAdminClient has been destroyed or disconnected.
218 webMethods Broker Administration Java API Programmer’s Guide Version 8.2
12 Java API Administration Reference
See Also:
BrokerAdminClient.getClientGroupInfos and BrokerAdminClient.getClientGroupNames
getClientGroupInfos
BrokerClientGroupInfo[] getClientGroupInfos( String client_group_names[]) throws BrokerException
Returns an array of BrokerClientGroupInfo objects containing the client groups' information. A null entry will be returned for each client group names you specify which could not be found or which your client does not have permission to browse.
See Also:
BrokerAdminClient.getClientGroupInfo, BrokerAdminClient.getClientGroupNames
getClientGroupLogAcknowledgeList
java.lang.String[]getClientGroupLogAcknowledgeList( java.lang.String client_group_name) throws BrokerException
Get the list of event types that are logged when they are acknowledged by a client in the the specified client group.
BrokerNoPermissionException The BrokerAdminClient does not have permission to read the client group's information.
BrokerNullParameterException The client_group_name parameter is null.
BrokerUnknownClientGroupException The specified client_group_name does not exist on the Broker.
client_group_names An array of names of the client groups whose information is to be returned.
Possible Exceptions Meaning
BrokerInvalidClientException The BrokerAdminClient has been destroyed or disconnected.
BrokerNullParameterException An entry in the client_group_names parameter is null.
client_group_name The name of the client group whose event types are to be logged.
Possible Exceptions Meaning
webMethods Broker Administration Java API Programmer’s Guide Version 8.2 219
12 Java API Administration Reference
getClientGroupLogPublishList
java.lang.String[]getClientGroupLogPublishList( java.lang.String client_group_name) throws BrokerException
Get the list of event types that are logged when published or delivered by a client in the specified client group.
getClientGroupNames
String[] getClientGroupNames() throws BrokerException
Returns an array of strings containing the names of all the client groups known to the Broker which your client has permission to browse.
See Also:
BrokerAdminClient.getClientGroupInfo and BrokerAdminClient.getClientGroupInfos
Possible Exceptions Meaning
BrokerInvalidClientException The BrokerAdminClient has been destroyed or disconnected.
BrokerNoPermissionException The BrokerAdminClient does not have permission to browse the client group's information.
BrokerNullParameterException The client_group_name parameter is null.
BrokerUnknownClientGroupException The specified client_group_name does not exist on the Broker.
client_group_name The name of the client group whose event types are to be logged.
Possible Exceptions Meaning
BrokerInvalidClientException The BrokerAdminClient has been destroyed or disconnected.
BrokerNoPermissionException The BrokerAdminClient does not have permission to browse the client group's information.
BrokerNullParameterException The client_group_name parameter is null.
BrokerUnknownClientGroupException The specified client_group_name does not exist on the Broker.
Possible Exceptions Meaning
BrokerInvalidClientException The BrokerAdminClient has been destroyed or disconnected.
220 webMethods Broker Administration Java API Programmer’s Guide Version 8.2
12 Java API Administration Reference
getClientGroupStats
BrokerEvent getClientGroupStats( String client_group_name) throws BrokerException
Returns a BrokerEvent object containing statistics for the specified client group.
The following table shows the events returned by the BrokerAdminClient.getClientGroupStats method.
See Also:
BrokerAdminClient.getBrokerStats, BrokerAdminClient.getClientStatsById, and BrokerAdminClient.getEventTypeStats
getClientGroupsWhichCanPublish
String[] getClientGroupsWhichCanPublish( String event_type_name) throws BrokerException
client_group_name The name of the client group whose statistics are to be returned.
Field Name Type Description
now BrokerDate Current time on the Broker host.
createTime BrokerDate The time the client group was created.
numEventsDelivered int The number of events delivered by all clients in this group.
numEventsPublished int The number of events published by all clients in this group.
lastEventDeliveryTime BrokerDate Time when an event was last delivered by a client in this group.
lastEventPublishTime BrokerDate Time when an event was last published by a client in this group.
lastUpdateTime BrokerDate Time when this group was last updated.
Possible Exceptions Meaning
BrokerInvalidClientException The BrokerAdminClient has been destroyed or disconnected.
BrokerNoPermissionException The BrokerAdminClient does not have permission to get the client group's statistics.
BrokerNullParameterException The client_group_name parameter is null.
BrokerUnknownClientGroupException The specified client_group_name does not exist on the Broker.
webMethods Broker Administration Java API Programmer’s Guide Version 8.2 221
12 Java API Administration Reference
Returns an array of strings containing the names of the client groups which can publish the specified event type. Only those client groups which your client has permission to browse will be returned. Clients may always browse their own client group.
Note: A zero length array will be returned if your client does not have permission to read the Broker's properties.
See Also:
BrokerAdminClient.getClientGroupsWhichCanPublish and BrokerAdminClient.setClientGroupCanPublishList
getClientGroupsWhichCanSubscribe
String[] getClientGroupsWhichCanSubscribe( String event_type_name) throws BrokerException
Returns an array of strings containing the names of the client groups which can subscribe to or receive a delivered event with the specified event type. Only those client groups which your client has permission to browse will be returned. Clients may always browse their own client group.
Note: A zero length array will be returned if your client does not have permission to read the Broker's properties.
event_type_name The name of the event type.
Possible Exceptions Meaning
BrokerInvalidClientException The BrokerAdminClient has been destroyed or disconnected.
BrokerNullParameterException The event_type_name parameter is null.
BrokerUnknownEventTypeException The specified event_type_name does not exist on the Broker.
event_type_name The name of the event type.
Possible Exceptions Meaning
BrokerInvalidClientException The BrokerAdminClient has been destroyed or disconnected.
BrokerNullParameterException The event_type_name parameter is null.
BrokerUnknownEventTypeException The specified event_type_name does not exist on the Broker.
222 webMethods Broker Administration Java API Programmer’s Guide Version 8.2
12 Java API Administration Reference
See Also:
BrokerAdminClient.getClientGroupCanSubscribeList and BrokerAdminClient.setClientGroupCanSubscribeList
getClientIds
String[] getClientIds() throws BrokerException
Returns an array of strings containing the identifiers of all the clients on the Broker which your client has permission to browse.
See Also:
BrokerAdminClient.getClientIdsByClientGroup and BrokerAdminClient.getClientIdsWhichAreSubscribed
getClientIdsByClientGroup
String[] getClientIdsByClientGroup( String client_group_name) throws BrokerException
Returns an array of strings containing the client identifiers of all Broker clients belonging to the specified client group which your client has permission to browse.
See Also:
BrokerAdminClient.getClientIds and BrokerAdminClient.getClientIdsWhichAreSubscribed
Possible Exceptions Meaning
BrokerInvalidClientException The BrokerAdminClient has been destroyed or disconnected.
client_group_name The name of the client group whose member client identifier list is to be returned.
Possible Exceptions Meaning
BrokerInvalidClientException The BrokerAdminClient has been destroyed or disconnected.
BrokerNoPermissionException The BrokerAdminClient does not have permission to get the list of client identifiers.
BrokerNullParameterException The client_group_name parameter is null.
BrokerUnknownClientGroupException The specified client_group_name does not exist on the Broker.
webMethods Broker Administration Java API Programmer’s Guide Version 8.2 223
12 Java API Administration Reference
getClientIdsWhichAreSubscribed
String[] getClientIdsWhichAreSubscribed( String event_type_name) throws BrokerException
Returns an array of strings containing the identifiers of the clients which have registered subscriptions for the specified event type. Only the identifiers for those client which your client has permission to browse will be returned.
See Also:
BrokerAdminClient.getClientIds and BrokerAdminClient.getClientIdsByClientGroup
getClientInfoById
BrokerClientInfo getClientInfoById( String client_id) throws BrokerException
Returns a BrokerClientInfo object containing information on the specified Broker client.
You can obtain a list of client identifiers by invoking the one of the following methods:
getClientIds
getClientIdsByClientGroup
getClientIdsWhichAreSubscribed
event_type_name The name of the event type.
Possible Exceptions Meaning
BrokerInvalidClientException The BrokerAdminClient has been destroyed or disconnected.
BrokerNullParameterException The event_type_name parameter is null.
BrokerUnknownEventTypeException The specified event_type_name does not exist on the Broker.
client_id The identifier of the client whose information is to be returned.
Possible Exceptions Meaning
BrokerInvalidClientException The BrokerAdminClient has been destroyed or disconnected.
BrokerNoPermissionException The BrokerAdminClient does not have permission to get the client information.
BrokerNullParameterException The client_id parameter is null.
BrokerUnknownClientIdException The specified client_id does not exist on the Broker.
224 webMethods Broker Administration Java API Programmer’s Guide Version 8.2
12 Java API Administration Reference
See Also:
BrokerAdminClient.getClientInfosById
getClientInfosById
BrokerClientInfo[] getClientInfosById( String client_ids[]) throws BrokerException
Returns an array of BrokerClientInfo objects containing information on the specified Broker clients. The array returned will be the same size as the client_ids array. The returned array may have null entries if:
The client identifier does not exist on the Broker.
This BrokerAdminClient does not have permission to read the Broker's properties.
You can obtain a list of client identifiers by invoking the one of the following methods:
getClientIds
getClientIdsByClientGroup
getClientIdsWhichAreSubscribed
See Also:
BrokerAdminClient.getClientInfoById
getClientInfosetById
BrokerEvent getClientInfosetById( String client_id) throws BrokerException
Returns the infoset for the Broker client with the specified client_id, which is returned as a BrokerEvent for convenience.
client_ids An array of identifiers for the clients whose information is to be returned.
Possible Exceptions Meaning
BrokerInvalidClientException The BrokerAdminClient has been destroyed or disconnected.
BrokerNullParameterException An entry in the client_ids array is null.
client_id The identifier of the Broker client whose infoset is to be returned.
webMethods Broker Administration Java API Programmer’s Guide Version 8.2 225
12 Java API Administration Reference
See Also:
BrokerAdminClient.setClientInfosetById
getClientQueueBrowsers
BrokerClientQueueBrowser[] getClientQueueBrowser(String client_id) throws BrokerException
Get information on the queue browsers that are opened by the specified client. Returns an array of BrokerClientQueueBrowser objects whose length corresponds to the number of active queue browsers on the specified client queue. Each of the BrokerClientQueueBrowser object holds details of the active queue browsers.
See Also:
BrokerAdminClient.createClientQueueBrowser and BrokerAdminClient.createLockedClientQueueBrowser
getClientQueueLock
Note: Support for the queue manipulation feature is dropped and replaced by the queue browser feature in webMethods Broker Java API version 6.5.
BrokerClientQueueLock getClientQueueLock( java.lang.String client_id) throws BrokerException
Possible Exceptions Meaning
BrokerInvalidClientException The BrokerAdminClient has been destroyed or disconnected.
BrokerNoPermissionException The BrokerAdminClient does not have permission to get the client infoset.
BrokerNullParameterException The client_id parameter is null.
BrokerUnknownClientIdException The specified client_id does not exist on the Broker.
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.
client_id Represents the id of the client whose queue will be locked.
flags (0) Not yet implemented. Returns BrokerClientQueueLock object.
226 webMethods Broker Administration Java API Programmer’s Guide Version 8.2
12 Java API Administration Reference
Use this method to lock the client queue. This method is used for queue manipulation. Returns a BrokerClientQueueLock object from which you can perform various operations on the client queue.
getClientStatsById
BrokerEvent getClientStatsById( String client_id) throws BrokerException
Returns BrokerEvent containing statistics for the specified Broker client.
The following table shows the events returned by the BrokerAdminClient.getClientStatsById method.
client_id The identifier of the client whose statistics are to be returned.
Field Name Type Description
now BrokerDate Current time on the Broker host.
createTime BrokerDate The time the client was created.
numEventsDelivered int The number of events delivered by the client.
numEventsPublished int The number of events published by the client.
numEventsRetrieved int The number of events retrieved by the client.
lastEventDeliveryTime BrokerDate Time when an event was last delivered by a client in this group. A value of zero means no event has ever been delivered.
lastEventPublishTime BrokerDate Time when an event was last published by a client in this group. A value of zero means no event has ever been published.
lastEventQueueTime BrokerDate Time when an event was last placed in this client's queue. A value of zero means no event has ever been queued.
lastEventRetrieveTime BrokerDate Time when an event was last retrieved from the queue by a client. A value of zero means no event has ever been retrieved.
queueLength long Number of events in the client's queue.
queueByteSize long The number of bytes of events in the client's queue.
queueHighestLength long Highest value of queue length, so far.
webMethods Broker Administration Java API Programmer’s Guide Version 8.2 227
12 Java API Administration Reference
You can obtain a list of client identifiers by invoking the one of the following methods:
getClientIds
getClientIdsByClientGroup
getClientIdsWhichAreSubscribed
See Also:
BrokerAdminClient.getBrokerStats, BrokerAdminClient.getClientGroupStats, and BrokerAdminClient.getEventTypeStats
getClientSubscriptionsById
BrokerSubscription[] getClientSubscriptionsById( String client_id) throws BrokerException
Returns an array of BrokerSubscription objects containing the event subscriptions that have been registered for the specified Broker client.
You can obtain a list of client identifiers by invoking the one of the following methods:
getClientIds
getClientIdsByClientGroup
getClientIdsWhichAreSubscribed
queueHighestLengthTime BrokerDate Time when queueHighestLength was last set. A value of zero means the client has never had an event queued.
Possible Exceptions Meaning
BrokerInvalidClientException The BrokerAdminClient has been destroyed or disconnected.
BrokerNoPermissionException The BrokerAdminClient does not have permission to get the client's statistics.
BrokerNullParameterException The client_id parameter is null.
BrokerUnknownClientIdException The specified client_id does not exist on the Broker.
client_id The identifier of the client whose subscriptions are to be returned.
Field Name Type Description
228 webMethods Broker Administration Java API Programmer’s Guide Version 8.2
12 Java API Administration Reference
See Also:
BrokerAdminClient.createClientSubscriptionById, BrokerAdminClient.createClientSubscriptionsById, BrokerAdminClient.destroyClientSubscriptionsById, BrokerAdminClient.destroyClientSubscriptionById, and BrokerAdminClient.doesClientSubscriptionExistById
getClusterACL
BrokerAccessControlList getClusterACL() throws BrokerException
Returns the access control list which the Brokers in the cluster are using to accept connections from other Brokers in remote cluster.
If access control is not being performed, the list will have zero entries. The list will have one entry if access control is enabled.
See Also:
BrokerAdminClient.setClusterACL
getClusterGatewayACL
BrokerAccessControlList getClusterGatewayACL( String cluster_name) throws BrokerException
Returns the access control list (ACL) this Broker uses to authenticate the connections with the remote Brokers that makes up the other half of the gateway.
Possible Exceptions Meaning
BrokerInvalidClientException The BrokerAdminClient has been destroyed or disconnected.
BrokerNoPermissionException The BrokerAdminClient does not have permission to get the client's subscription list.
BrokerNullParameterException The client_id parameter is null.
BrokerUnknownClientIdException The specified client_id does not exist on the Broker.
Possible Exceptions Meaning
BrokerInvalidClientException The BrokerAdminClient has been destroyed or disconnected.
BrokerNoPermissionException The BrokerAdminClient does not have permission to browse the Broker.
BrokerNotInClusterException The Broker is not a member of a cluster.
cluster_name The name of the cluster whose gateway ACL is to be returned.
webMethods Broker Administration Java API Programmer’s Guide Version 8.2 229
12 Java API Administration Reference
If access control is not being performed, the list will have zero entries. The list will have one entry if access control is enabled.
See Also:
BrokerAdminClient.setClusterGatewayACL.
getClusterGatewayKeepAlive
int getClusterGatewayKeepAlive( String cluster_name) throws BrokerException
This method returns the gateway Broker's keep-alive interval for the cluster specified in cluster_name. The keep-alive interval specifies the number of seconds of idle time after which the gateway Broker issues a keep-alive message to the cluster specified in cluster_name. A return value of 0 indicates that the keep-alive feature is disabled.
See also BrokerAdminClient.setClusterGatewayKeepAlive.
Possible Exceptions Meaning
BrokerInvalidClientException The BrokerAdminClient has been destroyed or disconnected.
BrokerNoPermissionException The BrokerAdminClient does not have permission to browse the Broker.
BrokerNotInClusterException The Broker is not a member of a cluster.
BrokerNullParameterException The cluster_name parameter value is null.
BrokerUnknownClusterException There is no gateway to the specified cluster from this client's Broker.
cluster_name The name of the cluster whose keep-alive status you want to check.
Possible Exceptions Meaning
BrokerInvalidClientException The BrokerAdminClient has been destroyed or disconnected.
BrokerNoPermissionException The BrokerAdminClient does not have permission to browse the Broker.
BrokerNotInClusterException The Broker is not a member of a cluster.
BrokerNullParameterException The cluster_name parameter value is null.
BrokerUnknownClusterException There is no gateway to the specified cluster from this client's Broker.
230 webMethods Broker Administration Java API Programmer’s Guide Version 8.2
12 Java API Administration Reference
getClusterGatewayRefuseAllUpdates
boolean getClusterGatewayRefuseAllUpdates( String cluster_name) throws BrokerException
Returns whether a cluster gateway refuses all the updates made in a connected cluster (true) or accepts all the updates (false).
See Also:
BrokerAdminClient.setClusterGatewayRefuseAllUpdates.
getClusterGatewaySharedEventTypes
BrokerSharedEventTypeInfo[] getClusterGatewaySharedEventTypes( String cluster_name, String broker_name) throws BrokerException
Gets the complete list of event types shared across a cluster gateway.
See BrokerSharedEventTypeInfo for more information.
cluster_name The name of the cluster to which the updates are accepted or refused.
Possible Exceptions Meaning
BrokerInvalidClientException The BrokerAdminClient has been destroyed or disconnected.
BrokerNoPermissionException The BrokerAdminClient does not have permission to browse the Broker.
BrokerNotInClusterException The Broker is not a member of a cluster.
BrokerNullParameterException The cluster_name parameter is null.
BrokerUnknownClusterException There is no gateway to the specified cluster from this client's Broker.
cluster_name The name of the cluster whose event types are shared.
broker_name The name of the Broker in the specified cluster. This Broker is used to identify the right gateway link for information retrieval.
Possible Exceptions Meaning
BrokerInvalidClientException The BrokerAdminClient has been destroyed or disconnected
BrokerNoPermissionException The client does not have permission to modify the Broker.
webMethods Broker Administration Java API Programmer’s Guide Version 8.2 231
12 Java API Administration Reference
See Also:
BrokerAdminClient.setClusterGatewaySharedEventTypes.
getClusterGatewayStats
BrokerEvent getClusterGatewayStats( String cluster_name, String broker_name) throws BrokerException
Returns a BrokerEvent containing statistics for the gateway for the specified cluster. For more information on the concept of cluster, see Administering webMethods Broker.
The following table shows the events returned by the BrokerAdminClient.getClusterGatewayStats method.
BrokerNotInClusterException If the specified Broker is not a member of the specified cluster.
BrokerNullParameterException The cluster_name or broker_name parameter value is null.
BrokerUnknownClusterException There is no gateway connection to the specified cluster from this Broker.
cluster_name The name of the cluster whose gateway statistics are to be returned.
broker_name The name of the Broker in the specified cluster. This Broker is used to identify the right gateway link for information retrieval.
Field Name Type Description
authProtocol unicode_string The protocol being used to authenticate the Broker. Only set if connectedFrom is not empty and authentication is used. Currently, the only supported value is "SSL".
authVersion unicode_string The version of the authentication protocol being used to authenticate the Broker. Only set if authProtocol is not empty. Currently supported values are "2" and "3".
connectedFrom unicode_string The IP address of the remote Broker. Set to an empty string if the gateway is not connected.
Possible Exceptions Meaning
232 webMethods Broker Administration Java API Programmer’s Guide Version 8.2
12 Java API Administration Reference
encryptLevel unicode_string The level of encryption being used. Only set if encryptProtocol is set. Currently supported values are "USDomestic" and "USExport".
encryptProtocol unicode_string The encryption protocol being used. Only set if connectedFrom is not empty. The only values currently supported is "SSL".
encryptVersion unicode_string The version of the encryption protocol being used. Only set if encryptProtocol is not empty. Currently supported values are "2" and "3".
gateway_pause boolean A flag indicating whether outbound traffic from this gateway Broker to cluster_name is enabled or disabled (paused). Will be true if outbound traffic to cluster_name has been paused. See setClusterGatewayPause.
gateway_pause_client String The client id of the BrokerAdminClient that paused the gateway. If outbound traffic is not currently paused for cluster_name, this parameter will be empty.
gateway_pause_session integer The session id from which the gateway was paused. If outbound traffic is not currently paused for cluster_name, this parameter will be 0.
gateway_pause_time date The time when the gateway was paused. If outbound traffic is not currently paused for cluster_name, this parameter will be 0.
gatewayBrokerName unicode_string The name of the gateway Broker.
gatewayHost unicode_string The name of the gateway Broker's host.
lastConnectTime Date The time the Broker was last connected. Set to zero if never connected.
lastEventEnqueueTime Date Time when an event was last enqueued for the gateway.
Field Name Type Description
webMethods Broker Administration Java API Programmer’s Guide Version 8.2 233
12 Java API Administration Reference
lastEventForwardTime Date Time when an event was last forwarded across the gateway. Set to zero if no events have been forwarded.
lastEventReceiveTime Date Time when an event was last received across the gateway. Set to zero if no events have been received.
now Date Current time on the Broker host.
numEventsForwarded int Number of events that were forwarded across the gateway.
numEventsReceived int The number of events received across the gateway.
numEventsEnqueued int Number of events enqueued for the gateway.
queueByteSize int The current size, in bytes, of the gateway's queue.
queueHighestLength int The highest number of events in the gateway's queue.
queueHighestLengthTime BrokerDate Time when queueHighestLength was last changed.
queueLength int The number of events currently in the gateway's queue.
remoteClusterName unicode_string The name of the cluster.
sslCertBeginDate Date The date of the Broker's certificate became valid.
sslCertSerialNumber unicode_string The serial number of the Broker's certificate. Set only if authProtocol is set to "SSL".
sslCertEndDate BrokerDate The date the Broker's certificate expires. Set only if authProtocol is set to "SSL"
sslCertStatus unicode_string The status of the other Broker's certificate. Set only if authProtocol is set to "SSL".
sslDistinguishedName unicode_string The distinguished name s of the other Broker's certificate. Set only if authProtocol is set to "SSL".
Field Name Type Description
234 webMethods Broker Administration Java API Programmer’s Guide Version 8.2
12 Java API Administration Reference
See Also:
BrokerAdminClient.addBrokerToCluster
getClusterInfo
BrokerClusterInfo getClusterInfo() throws BrokerException
Returns a BrokerClusterInfo object that contains the cluster settings.
getClusterStaticGatewayForwarding
boolean getClusterStaticGatewayForwarding(String cluster_name) throws BrokerException
This method returns the status of the current static gateway as true if the static gateway forwarding is set on the given remote cluster from the current Broker and false if the static gateway forwarding is not set.
sslIssuerDistinguishedName unicode_string The distinguished name s of the issuer of the other Broker's certificate. Set only if authProtocol is set to "SSL".
Possible Exceptions Meaning
BrokerInvalidClientException The BrokerAdminClient has been destroyed or disconnected.
BrokerNoPermissionException The BrokerAdminClient does not have permission to get the cluster statistics.
BrokerNotInClusterException This client's Broker is not part of a cluster.
BrokerNullParameterException The cluster_name or broker_name parameter is null.
BrokerUnknownClusterException There is no gateway to the specified cluster from this client's Broker.
Possible Exceptions Meaning
BrokerInvalidClientException The BrokerAdminClient has been destroyed or disconnected.
BrokerNoPermissionException The BrokerAdminClient does not have permission to browse the Broker.
BrokerNotInClusterException This client's Broker is not a member of a cluster.
cluster_name The name of the remote cluster.
Field Name Type Description
webMethods Broker Administration Java API Programmer’s Guide Version 8.2 235
12 Java API Administration Reference
See Also:
BrokerAdminClient.setClusterStaticGatewayForwarding
getClusterStats
BrokerEvent getClusterStats() throws BrokerException
Returns a BrokerEvent containing statistics for the cluster of this client's Broker. For more information on the concept of clusters, see Administering webMethods Broker.
The following table shows the fields returned by the BrokerAdminClient.getClusterStats method:
Possible Exceptions Meaning
BrokerInvalidClientException The client is not valid.
BrokerNotInClusterException The gateway Broker is not in a cluster.
BrokerUnknownClusterException On the current Broker, there is no local gateway to the specified remote cluster.
BrokerNullParameterException The cluster_name is null.
Field Name Type Description
brokers structure[] The time the event type was created. This includes changes to the definition, the time-to-live setting, or any infoset. A value of zero means there have been no changes since this event type was created
brokers.authProtocol unicode_string The protocol being used to authenticate the Broker. Only set if connectedFrom is not empty and authentication is used. Currently, the only supported value is "SSL".
brokers.authVersion unicode_string The version of the authentication protocol being used to authenticate the Broker. Only set if authProtocol is not empty. Currently supported values are "2" and "3".
236 webMethods Broker Administration Java API Programmer’s Guide Version 8.2
12 Java API Administration Reference
brokers.brokerHost unicode_string The Broker host name.
brokers.brokerName unicode_string The Broker Server name.
brokers.connectedFrom boolean Set to true if the Broker is currently connected.
brokers.description unicode_string The Broker's description.
brokers.encryptLevel unicode_string The level of encryption being used. Only set if encryptProtocol is set. Currently supported values are "USDomestic" and "USExport".
brokers.encryptProtocol unicode_string The encryption protocol being used. Only set if connectedFrom is not empty. The only values currently supported is "SSL".
brokers.encryptVersion unicode_string The version of the encryption protocol being used. Only set if encryptProtocol is not empty. Currently supported values are "2" and "3".
brokers.lastConnectTime BrokerDate The time the Broker was last connected. Set to zero if never connected.
brokers.lastEventEnqueueTime BrokerDate The time an event was last enqueued for the Broker. Set to zero if no events have ever be enqueued.
brokers.lastEventForwardTime BrokerDate Time when an event of this type was last forwarded to the Broker. Set to zero if no events have been forwarded.
brokers.lastEventReceiveTime BrokerDate Time when an event was last received by the Broker. Set to zero if no events have been received.
brokers.numEventsEnqueued int Number of events that were enqueued for the Broker.
Field Name Type Description
webMethods Broker Administration Java API Programmer’s Guide Version 8.2 237
12 Java API Administration Reference
brokers.numEventsForwarded int Number of events that were forwarded to the Broker.
brokers.numEventsReceived int The number of events received by the Broker.
brokers.queueByteSize int The current size, in bytes, of the Broker's queue.
brokers.queueHighestLength int The highest number of events in the Broker's queue.
brokers.queueHighestLengthTime BrokerDate Time when queueHighestLength was last changed.
brokers.queueLength int The number of events currently in the Broker's queue.
brokers.sslCertBeginDate BrokerDate The date of the Broker's certificate became valid.
brokers.sslCertSerialNumber unicode_string The serial number of the Broker's certificate. Set only if authProtocol is set to "SSL".
brokers.sslCertEndDate BrokerDate The date the Broker's certificate expires.
brokers.sslCertStatus unicode_string The status of the Broker's certificate. Set only if authProtocol is set to "SSL".
brokers.sslDistinguishedName unicode_string The distinguished name s of the Broker's certificate. Set only if authProtocol is set to "SSL".
brokers.sslIssuerDistinguishedName unicode_string The distinguished name s of the issuer of the other Broker's certificate. Set only if authProtocol is set to "SSL".
now BrokerDate Current time on the Broker host.
clusterName unicode_string The name of the cluster.
Field Name Type Description
238 webMethods Broker Administration Java API Programmer’s Guide Version 8.2
12 Java API Administration Reference
getEventAdminTypeDef
BrokerAdminTypeDef getEventAdminTypeDef( String event_type_name) throws BrokerException
Returns a BrokerAdminTypeDef object containing the type definition for the specified event type.
See Also:
BrokerAdminClient.destroyEventType, BrokerAdminClient.destroyEventTypes, BrokerAdminClient.getEventAdminTypeDef, BrokerAdminClient.getEventAdminTypeDefsByScope, BrokerAdminClient.setEventAdminTypeDef, and BrokerAdminClient.setEventAdminTypeDefs
getEventAdminTypeDefs
BrokerAdminTypeDef[] getEventAdminTypeDefs( String event_type_names[]) throws BrokerException
Returns an array of BrokerAdminTypeDef objects containing the type definitions for the specified event types. If event_type_names is null, this method returns all the event types that this client can browse. Clients may always browse those event types which they can publish or to which they can subscribe.
The array returned will be the same size as the event_type_names array. The returned array may have null entries if:
An event type does not exist on the Broker.
This BrokerAdminClient does not have permission to read the Broker's properties.
event_type_name The name of the event type whose type definition information is to be returned.
Possible Exceptions Meaning
BrokerInvalidClientException The BrokerAdminClient has been destroyed or disconnected.
BrokerNoPermissionException The BrokerAdminClient does not have permission to read the event type definition.
BrokerNullParameterException The event_type_name parameter is null.
BrokerUnknownEventTypeException The specified event_type_name does not exist on the Broker.
event_type_names An array containing the names of the event types whose type definition information are to be returned.
webMethods Broker Administration Java API Programmer’s Guide Version 8.2 239
12 Java API Administration Reference
Note: Clients always have read permission for the event types which they can publish or to which they may subscribe.
See Also:
BrokerAdminClient.destroyEventType, BrokerAdminClient.destroyEventTypes, BrokerAdminClient.getEventAdminTypeDef, BrokerAdminClient.getEventAdminTypeDefsByScope, BrokerAdminClient.setEventAdminTypeDef, and BrokerAdminClient.setEventAdminTypeDefs
getEventAdminTypeDefsByScope
BrokerAdminTypeDef[] getEventAdminTypeDefsByScope( String scope_name) throws BrokerException
Returns an array of BrokerAdminTypeDef objects containing the event type definitions for the event types in the specified scope.
Note: A zero length array will be returned if your client does not have permission to read any events within the specified scope. Clients always have read permission for the event types which they can publish or to which they may subscribe.
See Also:
BrokerAdminClient.destroyEventType, BrokerAdminClient.destroyEventTypes, BrokerAdminClient.getEventAdminTypeDef, BrokerAdminClient.getEventAdminTypeDefs, BrokerAdminClient.setEventAdminTypeDef, and BrokerAdminClient.setEventAdminTypeDefs
Possible Exceptions Meaning
BrokerInvalidClientException The BrokerAdminClient has been destroyed or disconnected.
BrokerNullParameterException The event_type_names parameter, or any element in that array is null.
scope_name The name of the scope whose event type definitions are to be returned.
Possible Exceptions Meaning
BrokerInvalidClientException The BrokerAdminClient has been destroyed or disconnected.
BrokerNullParameterException The scope_name parameter is null.
BrokerUnknownEventTypeException The scope does not exist on the Broker.
240 webMethods Broker Administration Java API Programmer’s Guide Version 8.2
12 Java API Administration Reference
getEventLogging
boolean getEventLogging() throws BrokerException
This method allows you to get the logging state on the current Broker. If this method returns false(0), logging has been disabled. No events will be logged. If this methods returns true(1), logging has been enabled. Events published and acknowledged will be logged.
getEventTypeStats
BrokerEvent getEventTypeStats( String event_type_name) throws BrokerException
Returns a BrokerEvent containing statistics for the specified event type.
The following table shows events returned by the BrokerAdminClient.getEventTypeStats method:
event_type_name The event type whose statistics are to be returned.
Field Name Type Description
createTime BrokerDate The time the event type was created.
lastEventDeliveryTime BrokerDate Time when an event of this type was last delivered on this Broker.
lastEventPublishTime BrokerDate Time when an event of this type was last published on this Broker.
lastForwardReceivedTime BrokerDate Time when an event of this type was last forwarded to this Broker by another Broker.
now BrokerDate Current time on the Broker host.
numClientSubscriptions int Number of open subscriptions which include this event type by Clients on this Broker.
numEventsDelivered int The number of events of this type that have been delivered on this Broker.
numEventsPublished int The number of events of this type that have been published on this Broker.
numForwardsReceived int Number of events of this type that were forwarded to this Broker by another Broker.
numGroupsCanPublish int Number of client groups that can publish this event type.
webMethods Broker Administration Java API Programmer’s Guide Version 8.2 241
12 Java API Administration Reference
See Also:
BrokerAdminClient.getBrokerStats, BrokerAdminClient.getClientGroupStats, and BrokerAdminClient.getClientStatsById
getHeuristicTransactions
BrokerEvent[] getHeuristicTransactions() throws BrokerException;
Returns a BrokerEvent containing the following information for the current heuristic transactions in the Broker transaction manager.
numGroupsCanSubscribe int Number of client groups that can subscribe to this event type.
updateTime BrokerDate The time the event type was last modified. This includes changes to the definition, the time-to-live setting, or any infoset. A value of zero means there have been no changes since this event type was created.
Possible Exceptions Meaning
BrokerInvalidClientException The BrokerAdminClient has been destroyed or disconnected.
BrokerNoPermissionException The BrokerAdminClient does not have permission to get the event's statistics.
BrokerNullParameterException The event_type_name parameter is null.
BrokerUnknownEventTypeException The specified event type does not exist on the Broker.
Field Name Type
now BrokerDate
transactions struct[]
transactions.transactionId long
transactions.externalId UnicodeString
transactions.clientId UnicodeString
transactions.sessionId int
transactions.state int
transactions.createdTime BrokerDate
Field Name Type Description
242 webMethods Broker Administration Java API Programmer’s Guide Version 8.2
12 Java API Administration Reference
See Also:
BrokerAdminClient.forgetForced
getLocalClusterGateways
BrokerClusterGatewayInfo[] getLocalClusterGateways() throws BrokerException
Returns a list of clusters for which this Broker is acting as a gateway.
See Also:
BrokerAdminClient.getAllClusterGateways
transactions.endedTime BrokerDate
transactions.preparedTime BrokerDate
transactions.closedTime BrokerDate
transactions.closedReason int
transactions.unpreparedTimeout BrokerDate
transactions.preparedTimeoutInterval int
transactions.preparedTimeout BrokerDate
transactions.numEventsReceived int
transactions.numEventsAcknowledged int
transactions.numEventsPublished int
Possible Exceptions Meaning
BrokerInvalidClientException The BrokerAdminClient has been destroyed or disconnected.
BrokerNoPermissionException The BrokerAdminClient does not have permission to browse the Broker.
Possible Exceptions Meaning
BrokerInvalidClientException The BrokerAdminClient has been destroyed or disconnected.
BrokerNoPermissionException The BrokerAdminClient does not have permission to browse the Broker.
BrokerNotInClusterException The Broker is not a member of a cluster.
Field Name Type
webMethods Broker Administration Java API Programmer’s Guide Version 8.2 243
12 Java API Administration Reference
getLocalTerritoryGateways
BrokerTerritoryGatewayInfo[] getLocalTerritoryGateways() throws BrokerException
Returns a list of territories for which this Broker is acting as a gateway.
See Also:
BrokerAdminClient.getAllTerritoryGateways
getLogEvents
BrokerEvent[] getLogEvents( int from_index, int max_events, int msecs) throws BrokerException
Gets one or more events from the Brokers event log at the given zero-based index. The number of events being returned is not guaranteed to be max_events even if there are more than max_events in the client's queue. Any number of events up to the value of max_events may be returned. In addition to the listed exceptions, any communications exception can be thrown. Throws an exception with the following major code setting: INVALID_CLIENT if the client is not valid. NULL_PARAM if n or events are NULL. In addition, any of the communications errors can occur.
Possible Exceptions Meaning
BrokerInvalidClientException The BrokerAdminClient has been destroyed or disconnected.
BrokerNoPermissionException The BrokerAdminClient does not have permission to browse the Broker.
BrokerNotInTerritoryException The Broker is not a member of a territory.
from_index Events to be logged starting from this index.
max_events Maximum number of events that may be logged.
msecs
Possible Exceptions Meaning
BrokerInvalidClientException The BrokerAdminClient has been destroyed or disconnected.
BrokerOutOfRangeException from_index is less than zero.
BrokerNullParameterException max_events, msecs equals zero.
BrokerTimeoutException Reply from Broker is null.
BrokerException XcellpadX
244 webMethods Broker Administration Java API Programmer’s Guide Version 8.2
12 Java API Administration Reference
getLogLength
int getLogLength() throws BrokerException
Returns the number of events in the Broker's log.
getPostPrepareTimeout
int getPostPrepareTimeout() throws BrokerException
Returns the default setting for the post-prepare time-out, in seconds. The post-prepare time-out is the period of time between the point when a transaction is prepared and when it is committed.
See Also:
BrokerAdminClient.setPrePrepareTimeout and BrokerAdminClient.getPostPrepareTimeoutAction
getPostPrepareTimeoutAction
int getPostPrepareTimeoutAction() throws BrokerException
Returns an integer representing the action that the Broker transaction manager will take when a prepared transactions times out (i.e., when the transaction is not committed within the time by the Broker's post-prepare time out period).
Possible Exceptions Meaning
BrokerInvalidClientException The client is not valid. In addition, any of the communications errors can occur.
Possible Exceptions Meaning
BrokerInvalidClientException The BrokerAdminClient has been destroyed or disconnected.
BrokerNoPermissionException The BrokerAdminClient does not have permission to browse the Broker.
BrokerIncompatibleVersionException The Broker does not support transaction administration.
Possible Exceptions Meaning
BrokerInvalidClientException The BrokerAdminClient has been destroyed or disconnected.
BrokerNoPermissionException The BrokerAdminClient does not have permission to browse the Broker.
BrokerIncompatibleVersionException The Broker does not support transaction administration.
webMethods Broker Administration Java API Programmer’s Guide Version 8.2 245
12 Java API Administration Reference
See Also:
BrokerAdminClient.setPostPrepareTimeoutAction and BrokerAdminClient.getPostPrepareTimeout
getPrePrepareTimeout
int getPrePrepareTimeout() throws BrokerException
Returns the setting for the pre-prepare time-out, in seconds. The pre-prepare time-out is the period of time between the point when a transaction begins, until it is asked to prepare.
See Also:
BrokerAdminClient.setPrePrepareTimeout
getRecoverMode
int getRecoverMode() throws BrokerException
Returns an integer representing the current recover-mode setting. The recover-mode setting determines whether the Broker transaction manager allows clients to recover any recoverable transaction (RECOVER_GLOBAL) or only those transaction in which they participated (RECOVER_RESTRICTED).
See Also:
BrokerAdminClient.setRecoverMode
getRemoteBrokerKeepAlive
void getRemoteBrokerKeepAlive( String broker_name) throws BrokerException
Possible Exceptions Meaning
BrokerInvalidClientException The BrokerAdminClient has been destroyed or disconnected.
BrokerNoPermissionException The BrokerAdminClient does not have permission to browse the Broker.
BrokerIncompatibleVersionException The Broker does not support transaction administration.
Possible Exceptions Meaning
BrokerInvalidClientException The BrokerAdminClient has been destroyed or disconnected.
BrokerNoPermissionException The BrokerAdminClient does not have permission to browse the Broker.
246 webMethods Broker Administration Java API Programmer’s Guide Version 8.2
12 Java API Administration Reference
This method returns the remote Broker's keep-alive interval to the Broker specified in broker_name. The keep-alive interval specifies the number of seconds of idle time after which the remote Broker issues a keep-alive message to the Broker specified in broker_name. A return value of 0 indicates that the keep-alive feature is disabled.
For more information, see “Maintaining a Connection Between Brokers in a Territory” on page 96 and “Maintaining a Connection Between Brokers in a Cluster” on page 108.
See also BrokerAdminClient.setRemoteBrokerKeepAlive
getStaticGatewayForwarding
boolean getStaticGatewayForwarding(String territory_name) throws BrokerException
This method returns the status of the current static gateway as: true if the static gateway forwarding is set on the given remote territory from the current Broker and false if the static gateway forwarding is not set.
See Also:
BrokerAdminClient.setStaticGatewayForwarding
getTerritoryACL
BrokerAccessControlList getTerritoryACL() throws BrokerException
Returns the access control list which Brokers in the territory are using to accept connections from other Brokers in their territory.
broker_name The name of the Broker whose keep-alive status you want to check.
Possible Exceptions Meaning
BrokerInvalidClientException The BrokerAdminClient has been destroyed or disconnected
BrokerNullParameterException territory_name is null
territory_name name of the remote territory
Possible Exceptions Meaning
BrokerInvalidClientException The client is not valid.
BrokerNotInTerritoryException The gateway Broker is not in a territory.
BrokerUnknownTerritoryException On the current Broker, there is no local gateway to the specified remote territory.
BrokerNullParameterException territory_name is full.
webMethods Broker Administration Java API Programmer’s Guide Version 8.2 247
12 Java API Administration Reference
If access control is not being performed, the list will have zero entries. The list will have one entry if access control is enabled.
See Also:
BrokerAdminClient.setTerritoryACL
getTerritoryGatewayACL
BrokerAccessControlList getTerritoryGatewayACL( String territory_name) throws BrokerException
Returns the access control list which this Broker is using to authenticate the remote Broker that makes up the other half of the gateway.
If access control is not being performed, the list will have zero entries. The list will have one entry if access control is enabled.
See Also:
BrokerAdminClient.setTerritoryGatewayKeepAlive
getTerritoryGatewayKeepAlive
int getTerritoryGatewayKeepAlive( String territory_name) throws BrokerException
Possible Exceptions Meaning
BrokerInvalidClientException The BrokerAdminClient has been destroyed or disconnected.
BrokerNoPermissionException The BrokerAdminClient does not have permission to browse the Broker.
BrokerNotInTerritoryException The Broker is not a member of a territory.
territory_name The name of the territory whose gateway ACL is to be returned.
Possible Exceptions Meaning
BrokerInvalidClientException The BrokerAdminClient has been destroyed or disconnected.
BrokerNoPermissionException The BrokerAdminClient does not have permission to browse the Broker.
BrokerNotInTerritoryException The Broker is not a member of a territory.
BrokerUnknownTerritoryException There is no gateway to the specified territory from this client's Broker.
248 webMethods Broker Administration Java API Programmer’s Guide Version 8.2
12 Java API Administration Reference
This method returns the gateway Broker's keep-alive interval for the territory specified in territory_name. The keep-alive interval specifies the number of seconds of idle time after which the gateway Broker issues a keep-alive message to the territory specified in territory_name. A return value of 0 indicates that the keep-alive feature is disabled.
See also BrokerAdminClient.setTerritoryGatewayKeepAlive
getTerritoryGatewayRefuseAllUpdates
public boolean getTerritoryGatewayRefuseAllUpdates( String territory_name) throws BrokerException
Returns whether a territory gateway refuses all updates made in a connected territory (true) or accepts all the updates (false).
See Also:
BrokerAdminClient.setTerritoryGatewayRefuseAllUpdates
territory_name The name of the territory whose keep-alive status you want to check.
Possible Exceptions Meaning
BrokerInvalidClientException The BrokerAdminClient has been destroyed or disconnected
BrokerNullParameterException territory_name is null
territory_name The name of the territory to which updates are accepted or refused.
Possible Exceptions Meaning
BrokerInvalidClientException The BrokerAdminClient has been destroyed or disconnected.
BrokerNoPermissionException The BrokerAdminClient does not have permission to browse the Broker.
BrokerNotInTerritoryException The Broker is not a member of a territory.
BrokerNullParameterException The territory_name parameter is null.
BrokerUnknownTerritoryException There is no gateway to the specified territory from this client's Broker.
webMethods Broker Administration Java API Programmer’s Guide Version 8.2 249
12 Java API Administration Reference
getTerritoryGatewayRefuseEventTypeUpdates
public void getTerritoryGatewayRefuseEventTypeUpdates( String territory_name, BrokerSharedEventTypeRefuseUpdateInfo[] infos) throws BrokerException
Returns information about whether updates for a document type that are made in a connected territory are refused.
See Also:
BrokerAdminClient.setTerritoryGatewayRefuseEventTypeUpdates
getTerritoryGatewaySharedEventTypes
void getTerritoryGatewaySharedEventTypes( String territory_name, BrokerSharedEventTypeInfo infos[]) throws BrokerException
Gets the complete list of event types shared across a territory gateway.
See BrokerSharedEventTypeInfo for more information.
territory_name The name of the territory for which updates made in a neighboring territory are refused.
infos Specifies whether the events and updates for a specified document type are refused.
Possible Exceptions Meaning
BrokerInvalidClientException The BrokerAdminClient has been destroyed or disconnected.
BrokerNoPermissionException The BrokerAdminClient does not have permission to browse the Broker.
BrokerNotInTerritoryException The Broker is not a member of a territory.
BrokerNullParameterException The territory_name parameter is null.
BrokerUnknownTerritoryException There is no gateway to the specified territory from this client's Broker.
territory_name The name of the territory whose event types are shared.
infos The shared event type information.
Possible Exceptions Meaning
BrokerInvalidClientException The BrokerAdminClient has been destroyed or disconnected
250 webMethods Broker Administration Java API Programmer’s Guide Version 8.2
12 Java API Administration Reference
See Also:
BrokerAdminClient.setTerritoryGatewaySharedEventTypes
getTerritoryGatewayStats
BrokerEvent getTerritoryGatewayStats( String territory_name) throws BrokerException
Returns a BrokerEvent containing statistics for the gateway for the specified territory. For more information on the concept of territories, see Administering webMethods Broker.
The following table shows events returned by the BrokerAdminClient.getTerritoryGatewayStats method.
BrokerInvalidSubscriptionException A parse error was encountered in one of the elements contained in infos.
BrokerInvalidTypeDefException One or more of the event types is incompatible with the type definition on the remote Broker.
BrokerNoPermissionException The client does not have permission to modify the Broker.
BrokerNotInTerritoryException The Broker to which this client is connected is not part of a territory.
BrokerNotRunningException The gateway connection is currently not open.
BrokerNullParameterException The territory_name or infos parameter is null, or an element in infos is null, or an element in infos has a nullevent_type_name.
BrokerOutOfRangeException An event type in infos does not have accept_subscribe permission, but has a non-empty subscription_filter.
BrokerUnknownEventTypeException An element in infos does not exist on either Broker in the gateway. If this exception is thrown, no changes are applied.
BrokerUnknownTerritoryException There is no gateway to the specified territory from the local Broker.
territory_name The name of the territory whose gateway statistics are to be returned.
Possible Exceptions Meaning
webMethods Broker Administration Java API Programmer’s Guide Version 8.2 251
12 Java API Administration Reference
Field Name Type Description
authProtocol unicode_string The protocol being used to authenticate the Broker. Only set if connectedFrom is not empty and authentication is used. Currently, the only supported value is "SSL".
authVersion unicode_string The version of the authentication protocol being used to authenticate the Broker. Only set if authProtocol is not empty. Currently supported values are "2" and "3".
connectedFrom unicode_string The IP address of the remote Broker. Set to an empty string if the gateway is not connected.
encryptLevel unicode_string The level of encryption being used. Only set if encryptProtocol is set. Currently supported values are "USDomestic" and "USExport".
encryptProtocol unicode_string The encryption protocol being used. Only set if connectedFrom is not empty. The only values currently supported is "SSL".
encryptVersion unicode_string The version of the encryption protocol being used. Only set if encryptProtocol is not empty. Currently supported values are "2" and "3".
gatewayHost unicode_string The name of the gateway Broker's host.
gatewayBrokerName unicode_string The name of the gateway Broker.
lastConnectTime BrokerDate The time the Broker was last connected. Set to zero if never connected.
lastEventEnqueueTime BrokerDate Time when an event was last enqueued for the gateway.
lastEventForwardTime BrokerDate Time when an event was last forwarded across the gateway. Set to zero if no events have been forwarded.
252 webMethods Broker Administration Java API Programmer’s Guide Version 8.2
12 Java API Administration Reference
lastEventReceiveTime BrokerDate Time when an event was last received across the gateway. Set to zero if no events have been received.
now BrokerDate Current time on the Broker host.
numEventsForwarded int Number of events that were forwarded across the gateway.
numEventsReceived int The number of events received across the gateway.
numEventsEnqueued int Number of events enqueued for the gateway.
queueByteSize int The current size, in bytes, of the gateway's queue.
queueHighestLength int The highest number of events in the gateway's queue.
queueHighestLengthTime BrokerDate Time when queueHighestLength was last changed.
queueLength int The number of events currently in the gateway's queue.
remoteTerritoryName unicode_string The name of the territory.
sslCertBeginDate BrokerDate The date of the Broker's certificate became valid.
sslCertSerialNumber unicode_string The serial number of the Broker's certificate. only set if authProtocol is set to "SSL".
sslCertEndDate BrokerDate The date the Broker's certificate expires.
sslCertStatus unicode_string The status of the other Broker's certificate. This field is only set if authProtocol is set to "SSL".
sslDistinguishedName unicode_string The distinguished name s of the other Broker's certificate. This field is only set if authProtocol is set to "SSL".
sslIssuerDistinguishedName unicode_string The distinguished name s of the issuer of the other Broker's certificate. This field is only set if authProtocol is set to "SSL".
Field Name Type Description
webMethods Broker Administration Java API Programmer’s Guide Version 8.2 253
12 Java API Administration Reference
See Also:
BrokerAdminClient.createTerritory
getTerritoryInfo
BrokerTerritoryInfo getTerritoryInfo() throws BrokerException
Returns a BrokerTerritoryInfo object that contains the territory settings for the Broker to which this client is connected.
gateway_pause boolean A flag indicating whether outbound traffic from this gateway Broker to territory_name is enabled or disabled (paused). Will be true if outbound traffic to territory_name has been paused. See setTerritoryGatewayPause.
gateway_pause_time date The time when the gateway was paused. If outbound traffic is not currently paused for territory_name, this parameter will be 0.
gateway_pause_client String The client id of the BrokerAdminClient that paused the gateway. If outbound traffic is not currently paused for territory_name, this parameter will be empty.
gateway_pause_session integer The session id from which the gateway was paused. If outbound traffic is not currently paused for territory_name, the value will be 0.
Possible Exceptions Meaning
BrokerInvalidClientException The BrokerAdminClient has been destroyed or disconnected.
BrokerNoPermissionException The BrokerAdminClient does not have permission to get the territory statistics.
BrokerNotInTerritoryException This client's Broker is not part of a territory.
BrokerNullParameterException The territory_name parameter is null.
BrokerUnknownTerritoryException There is no gateway to the specified territory from this client's Broker.
Field Name Type Description
254 webMethods Broker Administration Java API Programmer’s Guide Version 8.2
12 Java API Administration Reference
getTerritoryStats
BrokerEvent getTerritoryStats() throws BrokerException
Returns a BrokerEvent containing statistics for the territory of this client's Broker. For more information on the concept of territories, see Administering webMethods Broker. The following table shows events returned by the BrokerAdminClient.getTerritoryStats method:
Possible Exceptions Meaning
BrokerInvalidClientException The BrokerAdminClient has been destroyed or disconnected.
BrokerNoPermissionException The BrokerAdminClient does not have permission to get the territory statistics.
BrokerNotInTerritoryException This client's Broker is not part of a territory.
Field Name Type Description
brokers structure[] The time the event type was created. This includes changes to the definition, the time-to-live setting, or any infoset. A value of zero means there have been no changes since this event type was created
brokers.authProtocol unicode_string The protocol being used to authenticate the Broker. Only set if connectedFrom is not empty and authentication is used. Currently, the only supported value is "SSL".
brokers.authVersion unicode_string The version of the authentication protocol being used to authenticate the Broker. Only set if authProtocol is not empty. Currently supported values are "2" and "3".
brokers.brokerHost unicode_string The Broker host name.
brokers.brokerName unicode_string The Broker Server name.
brokers.connectedFrom boolean Set to true if the Broker is currently connected.
brokers.description unicode_string The Broker's description.
webMethods Broker Administration Java API Programmer’s Guide Version 8.2 255
12 Java API Administration Reference
brokers.encryptLevel unicode_string The level of encryption being used. Only set if encryptProtocol is set. Currently supported values are "USDomestic" and "USExport".
brokers.encryptProtocol unicode_string The encryption protocol being used. Only set if connectedFrom is not empty. The only values currently supported is "SSL".
brokers.encryptVersion unicode_string The version of the encryption protocol being used. Only set if encryptProtocol is not empty. Currently supported values are "2" and "3".
brokers.lastConnectTime BrokerDate The time the Broker was last connected. Set to zero if never connected.
brokers.lastEventEnqueueTime BrokerDate The time an event was last enqueued for the Broker. Set to zero if no events have ever be enqueued.
brokers.lastEventForwardTime BrokerDate Time when an event of this type was last forwarded to the Broker. Set to zero if no events have been forwarded.
brokers.lastEventReceiveTime BrokerDate Time when an event was last received by the Broker. Set to zero if no events have been received.
brokers.numEventsEnqueued int Number of events that were enqueued for the Broker.
brokers.numEventsForwarded int Number of events that were forwarded to the Broker.
brokers.numEventsReceived int The number of events received by the Broker.
brokers.queueByteSize int The current size, in bytes, of the Broker's queue.
brokers.queueHighestLength int The highest number of events in the Broker's queue.
Field Name Type Description
256 webMethods Broker Administration Java API Programmer’s Guide Version 8.2
12 Java API Administration Reference
brokers.queueHighestLengthTime BrokerDate Time when queueHighestLength was last changed.
brokers.queueLength int The number of events currently in the Broker's queue.
brokers.sslCertBeginDate BrokerDate The date of the Broker's certificate became valid.
brokers.sslCertSerialNumber unicode_string The serial number of the Broker's certificate. only set if authProtocol is set to "SSL".
brokers.sslCertEndDate BrokerDate The date the Broker's certificate expires.
brokers.sslCertStatus unicode_string The status of the Broker's certificate. This field is only set if authProtocol is set to "SSL".
brokers.sslDistinguishedName unicode_string The distinguished name s of the Broker's certificate. This field is only set if authProtocol is set to "SSL".
brokers.sslIssuerDistinguishedName unicode_string The distinguished name s of the issuer of the other Broker's certificate. This field is only set if authProtocol is set to "SSL".
now BrokerDate Current time on the Broker host.
territoryName unicode_string The name of the territory.
Possible Exceptions Meaning
BrokerInvalidClientException The BrokerAdminClient has been destroyed or disconnected.
BrokerNoPermissionException The BrokerAdminClient does not have permission to get the territory statistics.
BrokerNotInTerritoryException This client's Broker is not part of a territory.
Field Name Type Description
webMethods Broker Administration Java API Programmer’s Guide Version 8.2 257
12 Java API Administration Reference
See Also:
BrokerAdminClient.createTerritory, BrokerAdminClient.getBrokersInTerritory, BrokerAdminClient.joinTerritory, BrokerAdminClient.leaveTerritory, and BrokerAdminClient.removeBrokerFromTerritory
getTransactions
BrokerEvent getTransactions() throws BrokerException;
Returns a BrokerEvent containing the following information for the current transactions under the Broker transaction manager.
Field Name Type
now BrokerDate
transaction struct[]
transactions.transactionId long
transactions.externalId UnicodeString
transactions.clientId UnicodeString
transactions.sessionId int
transactions.state int
transactions.createdTime BrokerDate
transactions.endedTime BrokerDate
transactions.preparedTime BrokerDate
transactions.closedTime BrokerDate
transactions.closedReason int
transactions.unpreparedTimeout BrokerDate
transactions.preparedTimeoutInterval int
transactions.preparedTimeout BrokerDate
transactions.numEventsReceived int
transactions.numEventsAcknowledged int
transactions.numEventsPublished int
Exception Description
BrokerInvalidClientException The BrokerAdminClient has been destroyed or disconnected.
BrokerNoPermissionException The BrokerAdminClient does not have permission to get the territory statistics.
258 webMethods Broker Administration Java API Programmer’s Guide Version 8.2
12 Java API Administration Reference
See Also:
BrokerAdminClient.getTransactionsByClient
getTransactionsByClient
BrokerEvent getTransactionsByClient( String client_id) throws BrokerException;
Returns a BrokerEvent containing the following information for a given transactional client.
Field Name Type
now BrokerDate
transactions[] struct[]
transactions.transactionId long
transactions.externalId UnicodeString
transactions.clientId UnicodeString
transactions.sessionId int
transactions.state int
transactions.createdTime BrokerDate
transactions.endedTime BrokerDate
transactions.preparedTime BrokerDate
transactions.closedTime BrokerDate
transactions.closedReason int
transactions.unpreparedTimeout BrokerDate
transactions.preparedTimeoutInterval int
transactions.preparedTimeout BrokerDate
transactions.numEventsReceived int
transactions.numEventsAcknowledged int
transactions.numEventsPublished int
Exception Description
BrokerInvalidClientException The client has been destroyed or disconnected.
BrokerInvalidClientIdException client_id contains illegal characters.
BrokerNullParameterException client_id is null.
BrokerNoPermissionException Client does not have sufficient permissions.
webMethods Broker Administration Java API Programmer’s Guide Version 8.2 259
12 Java API Administration Reference
See Also:
BrokerAdminClient.getTransactions
join method
joinTerritory
BrokerJoinFailure joinTerritory( String broker_host, String broker_name) throws BrokerException
Causes this client's Broker join the territory of the Broker with the specified broker_name that is running on broker_host. If the join operation is successful, a null value is returned. Otherwise, a BrokerJoinFailureInfo object will be returned that describes the client groups and event types defined for this Broker that conflict with the territory's definitions.
For more information on the concept of territories, see Administering webMethods Broker.
broker_host The Broker host where broker_name is located. 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 whose territory this Broker is to join. whose territory this Broker is to join. This parameter may not be null.
Possible Exceptions Meaning
BrokerHostNotFoundException The specified broker_host does not exist.
BrokerInTerritoryException This client's Broker is already a member of a territory.
BrokerInvalidClientException The BrokerAdminClient has been destroyed or disconnected.
BrokerNoPermissionException The BrokerAdminClient does not have permission to modify the Broker's properties or the Broker is not licensed for Broker interconnection.
BrokerNotInTerritoryException The Broker specified by broker_name is not a member of a territory.
BrokerNullParameterException The parameter broker_host or broker_name is null.
BrokerOutOfRangeException There is another Broker in the specified territory with the same name
BrokerSecurityException If the territory requires SSL and the joining Broker does not support SSL.
260 webMethods Broker Administration Java API Programmer’s Guide Version 8.2
12 Java API Administration Reference
See Also:
BrokerAdminClient.createTerritory, BrokerAdminClient.getBrokersInTerritory, BrokerAdminClient.getTerritoryStats, BrokerAdminClient.leaveTerritory, and BrokerAdminClient.removeBrokerFromTerritory
leave Methods
leaveCluster
void leaveCluster( int msecs, boolean forced) throws BrokerException
Causes this client's Broker to leave its cluster. This operation may take time to complete because it requires communicating with other Brokers in the cluster. If msecs is not set to -1, a time-out exception may be thrown before the operation is completed. If forced is true, then the Broker will leave the cluster even if it cannot communicate with the other members of the cluster within the Broker's timeout period.
Note: Any other operation made on the Broker while this operation is in progress may also block and time out.
For more information on the concept of clusters, see Administering webMethods Broker.
BrokerUnknownBrokerNameException The specified broker_name does not exist on the specified broker_host.
msecs The number of milliseconds to wait for this operation to complete before timing out. If set to -1, this operation will never time out.
forced If set to true, the Broker will leave the cluster even if it cannot contact other cluster members within the specified time out interval.
Possible Exceptions Meaning
BrokerInvalidClientException The BrokerAdminClient has been destroyed or disconnected.
BrokerNoPermissionException The BrokerAdminClient does not have permission to modify the Broker's properties.
BrokerNotInClusterException The Broker is not a member of a cluster.
Possible Exceptions Meaning
webMethods Broker Administration Java API Programmer’s Guide Version 8.2 261
12 Java API Administration Reference
See Also:
BrokerAdminClient.createCluster, BrokerAdminClient.getBrokersInCluster, BrokerAdminClient.getClusterStats, BrokerAdminClient.addBrokerToCluster, and BrokerAdminClient.removeBrokerFromCluster
leaveTerritory
void leaveTerritory( int msecs, boolean forced) throws BrokerException
Causes this client's Broker to leave its territory. This operation may take time to complete because it requires communicating with other Brokers in the territory. If msecs is not set to -1, a time-out exception may be thrown before the operation has completed.
Note: Any other operation made on the Broker while this operation is in progress may also block and time out.
For more information on the concept of territories, see Administering webMethods Broker.
See Also:
BrokerAdminClient.createTerritory, BrokerAdminClient.getBrokersInTerritory, BrokerAdminClient.getTerritoryStats, BrokerAdminClient.joinTerritory, and BrokerAdminClient.removeBrokerFromTerritory
msecs The number of milliseconds to wait for this operation to complete before timing out. If set to -1, this operation will never time out.
forced If set to true, the Broker will leave the territory even if it cannot contact other territory members within the specified time out interval.
Possible Exceptions Meaning
BrokerInvalidClientException The BrokerAdminClient has been destroyed or disconnected.
BrokerNoPermissionException The BrokerAdminClient does not have permission to modify the Broker's properties.
BrokerNotInTerritoryException The Broker is not a member of a territory.
262 webMethods Broker Administration Java API Programmer’s Guide Version 8.2
12 Java API Administration Reference
new Method
newOrReconnectAdmin
static BrokerAdminClient newOrReconnectAdmin( String broker_host, String broker_name, String client_id, String client_group, String app_name, BrokerConnectionDescriptor desc) throws BrokerException
Attempts to create a new BrokerAdminClient with an event queue and zero subscriptions. If a BrokerAdminClient with the same client_id already exists, this client will be reconnected.
Note: For information on Broker name, client group name, and client identifier restrictions, see the webMethods Broker Client Java API Programmer’s Guide.
When finished with the BrokerAdminClient, the application is responsible for calling BrokerClient.disconnect or BrokerClient.destroy.
Note: When reconnecting, the client state sharing that was set when the BrokerAdminClient was originally created will be used. Client state sharing can only be enabled or disabled when creating new Broker clients, regardless of the information contained in the BrokerAdminDescriptor.
broker_host The name of the host where the Broker is running that the new 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 Server. If set to null, the default Broker name is used.
client_id The client identifier, identifying the client as the one that was previously disconnected. See the webMethods Broker Client Java API Programmer’s Guide for more information on client identifiers.
client_group The name of the client group for the new Broker client. Client groups are discussed in Administering webMethods Broker.
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 may be shared with other clients.
webMethods Broker Administration Java API Programmer’s Guide Version 8.2 263
12 Java API Administration Reference
See Also:
BrokerAdminClient.BrokerAdminClient, BrokerAdminClient.reconnectAdmin, as well as BrokerClient.destroy and BrokerClient.disconnect (described in the webMethods Broker Client Java API Programmer’s Guide)
reconnect Method
reconnectAdmin
static BrokerAdminClient reconnectAdmin( String broker_host, String broker_name, String client_id, BrokerConnectionDescriptor desc) 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 as an administrative client 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.
BrokerUnknownBrokerNameException The specified broker_name does not exist. If broker_name was null, then there is no default Broker.
BrokerUnknownClientGroupException The specified client_group_name does not exist on the Broker.
BrokerUnknownClientIdException The specified client_id does not exist on the Broker.
broker_host The name of the host where the Broker is running that the new 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
264 webMethods Broker Administration Java API Programmer’s Guide Version 8.2
12 Java API Administration Reference
Reconnects a previously disconnected BrokerAdminClient to a Broker so that the client can resume event processing. The client_id parameter identifies the BrokerAdminClient as one you previously disconnected using BrokerClient.disconnect.
Note: For information on Broker name, client group name, and client identifier restrictions, see the webMethods Broker Client Java API Programmer’s Guide.
When finished with the BrokerAdminClient, the application is responsible for calling BrokerClient.disconnect or BrokerClient.destroy.
In addition to reconnecting a previously disconnected BrokerAdminClient, this method may be used to connect a BrokerAdminClient that wants to share client state with another BrokerAdminClient.
Note: When reconnecting, the client state sharing that was set when the BrokerAdminClient was originally created will be used, regardless of the settings in the BrokerConnectionDescriptor.
broker_name The name of the Broker Server. If set to null, the default Broker name is used.
client_id The client identifier, identifying the client as the one that was previously disconnected. See the webMethods Broker Client Java API Programmer’s Guide for more information on client identifiers.
desc The connection descriptor to use for the client. If set to null, a default connection will be established which may 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.
BrokerInvalidClientIdException The client_id contains invalid characters.
BrokerNoPermissionException Permission to join the client_group as an administrative client was denied.
BrokerNotRunningException A Broker could not be found on the broker_host.
BrokerNullParameterException The broker_host or client_id parameter is null.
webMethods Broker Administration Java API Programmer’s Guide Version 8.2 265
12 Java API Administration Reference
See Also:
BrokerAdminClient.BrokerAdminClient and BrokerAdminClient.newOrReconnectAdmin, as well as BrokerClient.destroy and BrokerClient.disconnect (described in the webMethods Broker Client Java API Programmer’s Guide)
release Method
releaseChangeLock
void releaseChangeLock() throws BrokerException
Releases the change lock being held by this client for its Broker.
An exception will be thrown if the Broker to which this client is connected is not currently locked, or if the lock is held by another client.
See Also:
BrokerAdminClient.acquireChangeLock
remove Methods
removeBrokerFromCluster
void removeBrokerFromCluster( String broker_host, String broker_name) throws BrokerException
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.
Possible Exceptions Meaning
BrokerBadStateException The client's Broker is currently not locked or the lock is being held by another client.
BrokerIncompatibleVersionException The Broker Server does not support this operation.
BrokerInvalidClientException The BrokerAdminClient has been destroyed or disconnected.
Possible Exceptions Meaning
266 webMethods Broker Administration Java API Programmer’s Guide Version 8.2
12 Java API Administration Reference
Forces the removal of the specified Broker Server on the specified Broker host from the cluster. This method will return as soon as this Broker has started the process of removing the specified Broker from the cluster. It may return before other members of the cluster have been notified.
For more information on the concept of clusters, see Administering webMethods Broker.
See Also:
BrokerAdminClient.createCluster, BrokerAdminClient.getBrokersInCluster, BrokerAdminClient.getClusterStats, BrokerAdminClient.addBrokerToCluster, and BrokerAdminClient.leaveCluster.
removeBrokerFromTerritory
void removeBrokerFromTerritory( String broker_host, String broker_name) throws BrokerException
broker_host The Broker host where broker_name is located. 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 Server to be removed from the cluster to which this client's Broker belongs.
Possible Exceptions Meaning
BrokerHostNotFoundException The specified host cannot be located.
BrokerInvalidClientException The BrokerAdminClient has been destroyed or disconnected.
BrokerNoPermissionException The BrokerAdminClient does not have permission to modify the Broker's properties.
BrokerNotInClusterException The Broker to which this BrokerAdminClient is connected is not in any cluster.
BrokerNullParameterException The parameter broker_host or broker_name is null.
BrokerOutOfRangeException An attempt was made to remove the current Broker.
BrokerUnknownBrokerNameException The specified broker_name on the specified broker_host is not a member of the cluster.
webMethods Broker Administration Java API Programmer’s Guide Version 8.2 267
12 Java API Administration Reference
Forces the removal of the specified Broker Server on the specified Broker host from the territory. This method will return as soon as this Broker has started the process of removing the specified Broker from the territory. It may return before other members of the territory have been notified.
For more information on the concept of territories, see Administering webMethods Broker.
See Also:
BrokerAdminClient.createTerritory, BrokerAdminClient.getBrokersInTerritory, BrokerAdminClient.getTerritoryStats, BrokerAdminClient.joinTerritory, and BrokerAdminClient.leaveTerritory
set Methods
setBrokerDescription
void setBrokerDescription( String description) throws BrokerException
broker_host The Broker host where broker_name is located. 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 Server to be removed from the territory to which this client's Broker belongs.
Possible Exceptions Meaning
BrokerHostNotFoundException The specified host cannot be located.
BrokerInvalidClientException The BrokerAdminClient has been destroyed or disconnected.
BrokerNoPermissionException The BrokerAdminClient does not have permission to modify the Broker's properties.
BrokerNotInTerritoryException The Broker to which this BrokerAdminClient is connected is not in any territory.
BrokerNullParameterException The parameter broker_host or broker_name is null.
BrokerOutOfRangeException An attempt was made to remove the current Broker.
BrokerUnknownBrokerNameException The specified broker_name on the specified broker_host is not a member of the territory.
description A string containing the new description to be set for the Broker.
268 webMethods Broker Administration Java API Programmer’s Guide Version 8.2
12 Java API Administration Reference
Sets the description for the Broker to which this BrokerAdminClient is connected. The description is a comment field that will be displayed by the webMethods Broker administration tools and can contain any information you want.
See Also:
BrokerAdminClient.getBrokerDescription
setClientGroupAccessLabelRequired
void setClientGroupAccessLabelRequired( String client_group_name, boolean required) throws BrokerException
Sets whether or not an access label is required for creating a client in the specified client group. A client group's current access label requirements can be determined using the BrokerAdminClient.getClientGroupInfo method.
See Also:
BrokerAdminClient.getClientGroupInfo
Possible Exceptions Meaning
BrokerInvalidClientException The BrokerAdminClient has been destroyed or disconnected.
BrokerNoPermissionException The BrokerAdminClient does not have permission to set the Broker's description.
BrokerNullParameterException The description parameter is null.
client_group_name A string containing the name of the client group whose access control list is to be set.
required If set to true, an access label will be required.
Possible Exceptions Meaning
BrokerInvalidClientException The BrokerAdminClient has been destroyed or disconnected.
BrokerNoPermissionException The BrokerAdminClient does not have permission to modify the client group.
BrokerNullParameterException The client_group_name parameter is null.
BrokerUnknownClientGroupException The specified client_group_name does not exist on the Broker.
webMethods Broker Administration Java API Programmer’s Guide Version 8.2 269
12 Java API Administration Reference
setClientGroupACL
void setClientGroupACL( String client_group_name, BrokerAcessControlList acl) throws BrokerException
Sets the list of names that are allowed to create Broker clients which belong to the specified client group.
See AccessControlList for more information.
See Also:
BrokerAdminClient.getClientGroupACL
setClientGroupCanPublishList
void setClientGroupCanPublishList( String client_group_name, String event_type_names[]) throws BrokerException
Sets the list of event type names that can be published or delivered by the specified client group. Any event type names previously set in the can-publish list will be replaced by the new list.
client_group_name A string containing the name of the client group whose access control list is to be set.
acl The access control list to set.
Possible Exceptions Meaning
BrokerInvalidAccessListException The access control list is invalid.
BrokerInvalidClientException The BrokerAdminClient has been destroyed or disconnected.
BrokerNoPermissionException The BrokerAdminClient does not have permission to set the client group's Access Control List.
BrokerNullParameterException The client_group_name or acl parameter is null.
BrokerUnknownClientGroupException The specified client_group_name does not exist on the Broker.
client_group_name A string containing the name of the client group whose can-publish list is to be set.
event_type_names An array of strings containing the event type names to be set as the can-publish list.
270 webMethods Broker Administration Java API Programmer’s Guide Version 8.2
12 Java API Administration Reference
See Also:
BrokerAdminClient.getClientGroupCanPublishList, BrokerAdminClient.getClientGroupCanSubscribeList, and BrokerAdminClient.setClientGroupCanSubscribeList
setClientGroupCanSubscribeList
void setClientGroupCanSubscribeList( String client_group_name, String event_type_names[]) throws BrokerException
Sets the list of event type names to which members of the client group can subscribe or which may be delivered to members of the client group. Any event type names previously set in the can-subscribe list will be replaced by the new list.
Possible Exceptions Meaning
BrokerInvalidClientException The BrokerAdminClient has been destroyed or disconnected.
BrokerNoPermissionException The BrokerAdminClient does not have permission to set the client group's can-publish list.
BrokerNullParameterException The client_group_name or event_type_names parameter was null or an entry in the event_type_names array is null.
BrokerUnknownClientGroupException The specified client_group_name does not exist on the Broker.
BrokerUnknownEventTypeException One of the event types specified in the event_type_names array does not exist on the Broker. If this exception is thrown, the client group's original can-publish list will not be altered.
client_group_name A string containing the name of the client group whose can-subscribe list is to be set.
event_type_names An array of strings containing the event type names to be set as the can-subscribe list.
Possible Exceptions Meaning
BrokerInvalidClientException The BrokerAdminClient has been destroyed or disconnected.
BrokerNoPermissionException The BrokerAdminClient does not have permission to set the client group's can-publish list.
BrokerNullParameterException The client_group_name parameter was null or an entry in the event_type_names array is null.
webMethods Broker Administration Java API Programmer’s Guide Version 8.2 271
12 Java API Administration Reference
See Also:
BrokerAdminClient.getClientGroupCanSubscribeList, BrokerAdminClient.getClientGroupCanPublishList, and BrokerAdminClient.setClientGroupCanPublishList
setClientGroupDescription
void setClientGroupDescription( String client_group_name, String description) throws BrokerException
Sets the description of the specified client group. You can use the BrokerAdminClient.getClientGroupInfo method to retrieve the description.
See Also:
BrokerAdminClient.getClientGroupInfo and BrokerAdminClient.getClientGroupNames
BrokerUnknownClientGroupException The specified client_group_name does not exist on the Broker.
BrokerUnknownEventTypeException One of the event types specified in the event_type_names array does not exist on the Broker. If this exception is thrown, the client group's original can-subscribe list will not be altered.
client_group_name A string containing the name of the client group whose description is to be set.
description A string containing the description to be set for the client group.
Possible Exceptions Meaning
BrokerInvalidClientException The BrokerAdminClient has been destroyed or disconnected.
BrokerNoPermissionException The BrokerAdminClient does not have permission to set the client group's description.
BrokerNullParameterException The client_group_name or description parameter is null.
BrokerUnknownClientGroupException The specified client_group_name does not exist on the Broker.
Possible Exceptions Meaning
272 webMethods Broker Administration Java API Programmer’s Guide Version 8.2
12 Java API Administration Reference
setClientGroupLogAcknowledgeList
void setClientGroupLogAcknowledgeList( java.lang.String client_group_name, java.lang.String[] event_type_names) throws BrokerException
Set the list of event types that are logged when acknowledged by a client in the specified client group.
setClientGroupLogPublishList
void setClientGroupLogPublishList( java.lang.String client_group_name, java.lang.String[] event_type_names) throws BrokerException
Set the list of event types that are logged when published or delivered by a client in the the specified client group.
client_group_name The name of the client group whose event types are to be logged.
event_type_names List of the event type names to be logged.
Possible Exceptions Meaning
BrokerInvalidClientException The client has been destroyed or disconnected.
BrokerNoPermissionException The client does not have permission to modify the client group.
BrokerNullParameterException If client_group_name or event_type_names is null, or if any entry in the array is null.
BrokerUnknownEventTypeException If an event type is listed that does not exist in the Broker. In this case, the can publish list is not altered.
client_group_name The name of the client group whose event types are to be logged.
event_type_names List of the event type names to be logged.
Possible Exceptions Meaning
BrokerInvalidClientException The client has been destroyed or disconnected.
BrokerNoPermissionException The client does not have permission to modify the client group.
BrokerNullParameterException If client_group_name or event_type_names is null, or if any entry in the array is null.
webMethods Broker Administration Java API Programmer’s Guide Version 8.2 273
12 Java API Administration Reference
setClientGroupRequiredEncryption
void setClientGroupRequiredEncryption( String client_group_name, int level) throws BrokerException
Set the required encryption for the specified client group.
This client group's current value can be acquired using the BrokerAdminClient.getClientGroupInfo method.
See Also:
BrokerAdminClient.getClientGroupInfo
setClientInfosetById
void setClientInfosetById( String client_id, BrokerEvent infoset) throws BrokerException
BrokerUnknownEventTypeException If an event type is listed that does not exist in the Broker. In this case, the can publish list is not altered.
client_group_name The name of the client group whose required encryption level is being set.
level The level of encryption required by the client group. Must be a BrokerConnectionDescriptorENCRYPT_LEVEL_* values described in the webMethods Broker Client Java API Programmer’s Guide.
Possible Exceptions Meaning
BrokerInvalidClientException The BrokerAdminClient has been destroyed or disconnected.
BrokerNoPermissionException The BrokerAdminClient does not have permission to modify the properties of the specified client group.
BrokerNullParameterException The client _group parameter is null.
BrokerOutOfRangeException The parameter level contains an invalid value.
BrokerUnknownClientGroupException The specified client group does not exist on the Broker.
client_id The identifier of the Broker client whose infoset is to be returned.
Possible Exceptions Meaning
274 webMethods Broker Administration Java API Programmer’s Guide Version 8.2
12 Java API Administration Reference
Sets the client infoset for the Broker client with the specified client_id. The infoset is passed as a BrokerEvent for convenience.
Note: For information on infoset name and infoset field name restrictions, see the webMethods Broker Client Java API Programmer’s Guide.
See Also:
BrokerAdminClient.getClientInfosetById
setClientLastPublishSequenceNumberById
void setClientLastPublishSequenceNumberById( String client_id, long seqn) throws BrokerException
Sets the high publisher sequence number for the specified Broker client. This is sequence number from the event most recently by the client. The Broker stores this sequence number and uses it to recognized and discard duplicate events which may be published by the Broker client.
The current last-published sequence number can be acquiring using the BrokerAdminClient.getClientInfoById method.
infoset The infoset to be set for the Broker client.
Possible Exceptions Meaning
BrokerInvalidClientException The BrokerAdminClient has been destroyed or disconnected.
BrokerNoPermissionException The BrokerAdminClient does not have permission to modify the properties of the specified Broker client.
BrokerNullParameterException The client_id or infoset parameter is null.
BrokerUnknownClientIdException The specified client does not exist on the Broker.
client_id A string containing the client identifier whose last-published sequence number is to be set.
seqn The new last-published sequence number to set.
Possible Exceptions Meaning
BrokerInvalidClientException The BrokerAdminClient has been destroyed or disconnected.
webMethods Broker Administration Java API Programmer’s Guide Version 8.2 275
12 Java API Administration Reference
See Also:
BrokerAdminClient.getClientInfoById
setClientStateShareLimitById
void setClientStateShareLimitById( String client_id, int limit) throws BrokerException
Sets the number of clients which can simultaneously connect using the same client identifier as the Broker client with the specified client_id. You can obtain the current state sharing limit by using the BrokerAdminClient.getClientInfoById method.
Note: This method can only be used to alter those Broker clients who are currently enabled to share their state. For more information, refer to the BrokerConnectionDescriptor class description in the webMethods Broker Client Java API Programmer’s Guide.
You can obtain a list of client identifiers by invoking the one of the following methods:
getClientIds
getClientIdsByClientGroup
getClientIdsWhichAreSubscribed
BrokerNoPermissionException The BrokerAdminClient does not have permission to modify the properties of the specified Broker client.
BrokerNullParameterException The client_id parameter is null.
BrokerOutOfRangeException The seqn parameter is less than zero.
BrokerUnknownClientIdException The specified client does not exist on the Broker.
client_id A string containing the client identifier whose state share limit is to be set.
limit The new limit to be set. Setting a value of -1 indicates there is no limit to the number of clients that may share state with the specified client.
Possible Exceptions Meaning
BrokerInvalidClientException The BrokerAdminClient has been destroyed or disconnected.
BrokerNoPermissionException The BrokerAdminClient does not have permission to modify the client's queue or the client is not currently sharing its state.
Possible Exceptions Meaning
276 webMethods Broker Administration Java API Programmer’s Guide Version 8.2
12 Java API Administration Reference
See Also:
BrokerAdminClient.getClientInfoById
setClusterACL
void setClusterACL( BrokerAccessControlList acl) throws BrokerException
Sets the access control list used by Broker's in this cluster to accept connections from other Brokers in the cluster. Changing the cluster's ACL will not cause existing inter-Broker connections to fail.
For more information on clusters, see Administering webMethods Broker.
Important! If you use this method to disallow a user identity that is currently being used by a member of the cluster, your cluster will become partially disconnected.
See Also:
BrokerAdminClient.getClusterACL
BrokerNullParameterException The client_id parameter is null.
BrokerOutOfRangeException The limit parameter is zero or less than -1.
BrokerUnknownClientIdException The specified client_id does not exist on the Broker.
acl The access control list to set for this Broker's cluster.
Possible Exceptions Meaning
BrokerInvalidAccessListException The acl variable does not contain a valid access control list.
BrokerInvalidClientException The BrokerAdminClient has been destroyed or disconnected.
BrokerNoPermissionException The BrokerAdminClient does not have permission to modify the Broker.
BrokerNotInClusterException The Broker to which this client is connected is not part of a cluster.
BrokerNullParameterException The acl parameter is null.
Possible Exceptions Meaning
webMethods Broker Administration Java API Programmer’s Guide Version 8.2 277
12 Java API Administration Reference
setClusterGatewayACL
void setClusterGatewayACL( String cluster_name, String broker_name, BrokerAccessControlList acl) throws BrokerException
Set the access control list (ACL) which this Broker will use to accept connections from the other Broker in he cluster gateway.
The access control list can contain either one entry or no entries in each of the user and authenticator lists. Changing the current access control list will not cause an existing gateway connection to fail.
Important! If you use this method to disallow a user identity that is currently being used by the other Broker in the cluster gateway, the gateway will become disconnected.
See Also:
BrokerAdminClient.getClusterGatewayACL
cluster_name The name of the cluster whose gateway ACL is to be set.
broker_name The name of the Broker in the specified remote cluster to which the ACL is to be set.
acl The access control list.
Possible Exceptions Meaning
BrokerInvalidAccessListException The acl variable does not contain a valid access control list.
BrokerInvalidClientException The BrokerAdminClient has been destroyed or disconnected.
BrokerNoPermissionException The BrokerAdminClient does not have permission to modify the Broker.
BrokerNotInClusterException The Broker to which this client is connected is not part of a cluster.
BrokerNullParameterException The cluster_name, broker_name or acl parameter is null.
BrokerOutOfRangeException The acl contains more than one user entry or more than one authenticator entry.
BrokerUnknownClusterException There is no gateway to the specified cluster from this Broker.
278 webMethods Broker Administration Java API Programmer’s Guide Version 8.2
12 Java API Administration Reference
setClusterGatewayKeepAlive
void setClusterGatewayKeepAlive( String cluster_name, String broker_name, int KeepAlive) throws BrokerException
This method enables or disables the keep-alive feature on the cluster gateway Broker. When enabled, the gateway Broker issues 'keep-alive' messages to the cluster specified in cluster-name.
The keep-alive feature is useful when the firewalls separating gateway Brokers are programmed to drop connections that are idle for extended periods. To prevent the firewall from dropping the connection between the gateway Brokers, you use the keep-alive feature to generate enough traffic to keep the connection alive.
Setting KeepAlive to a positive number instructs the gateway Broker to issue keep-alive messages when its connection to cluster_name or broker_name is idle longer than the KeepAlive period (in seconds).
For more information about the keep-alive feature, see “Maintaining a Connection Between Gateway Brokers” on page 100.
cluster_name The name of the cluster to which you want the gateway Broker to issue keep-alive messages.
broker_name The name of the gateway Broker in the specified remote cluster you want to enable or disable keep-alive messages.
KeepAlive The frequency, in number of seconds, with which the gateway Broker will issue keep-alive messages to cluster_name. Set KeepAlive to 0 to disable keep-alive messages.
Possible Exceptions Meaning
BrokerInvalidClientException The BrokerAdminClient has been destroyed or disconnected
BrokerNullParameterException The cluster_name or broker_name parameter is null.
BrokerOutOfRageException The value of KeepAlive is less than Zero (0).
BrokerNoPermissionException The BrokerAdminClient does not have permission to modify the Broker.
BrokerNotInClusterException The Broker to which this client is connected is not part of a cluster.
BrokerUnknownClusterException There is no gateway to the specified cluster from this Broker.
BrokerIncompatibleVersionException Gateway Broker does not support the keep-alive feature.
webMethods Broker Administration Java API Programmer’s Guide Version 8.2 279
12 Java API Administration Reference
See also BrokerAdminClient.getClusterGatewayKeepAlive
setClusterGatewayPause
void setClusterGatewayPause( String cluster_name, String broker_name, boolean pause) throws BrokerException
This methods prevents the gateway Broker from forwarding events to the cluster in cluster_name. Once the gateway has been paused, the gateway Broker will hold events for the specified cluster until the pause state is explicitly cleared by setting pause to false.
To check whether outbound events to another cluster have been are paused, check the gateway_pause value returned by getClusterGatewayStats.
cluster_name The name of the cluster whose events you want the gateway Broker to hold.
broker_name The name of the gateway Broker in the specified cluster to which you want to prevent from forwarding events.
pause Flag indicating whether the gateway Broker is to pause or resume the transmission of events to the cluster in cluster_name. Set to true to halt the forwarding of events to cluster_name. Set to false to resume sending events to cluster_name.
Possible Exceptions Meaning
BrokerInvalidClientException The BrokerAdminClient has been destroyed or disconnected.
BrokerNullParameterException The cluster_name or broker_name is null.
BrokerBadStateException The cluster gateway is already paused or resumed.
BrokerNoPermissionException The BrokerAdminClient does not have permission to modify the Broker.
BrokerNotInClusterException The Broker to which this client is connected is not a member of a cluster.
BrokerUnknownClusterException There is no gateway to the specified cluster from this Broker.
BrokerIncompatibleVersionException The gateway Broker does not support this feature.
BrokerQueueBrowserException The gateway forwarding queue is locked by a queue browser.
280 webMethods Broker Administration Java API Programmer’s Guide Version 8.2
12 Java API Administration Reference
setClusterGatewayRefuseAllUpdates
void setClusterGatewayRefuseAllUpdates( String cluster_name, String broker_name, boolean refuse_updates) throws BrokerException
Set whether a cluster gateway will refuse all updates to shared document types made in a connected cluster.
If the refuse_updates parameter is set to true, all updates from the specified cluster are refused. However, the individual settings for each event type are retained, so that when refuse_updates parameter is set back to false, the original event type settings are reset.
See Also:
BrokerAdminClient.getClusterGatewayRefuseAllUpdates
setClusterGatewaySecurity
void setClusterGatewaySecurity( String cluster_name, String broker_name, int auth_type, int encrypt_level) throws BrokerException
cluster_name The name of the cluster to which updates are refused.
broker_name The name of the Broker in the specified cluster. This Broker is used to identify the right gateway link for setting this permission.
refuse_updates Specify whether the cluster will refuse all updates from a neighboring cluster connected by a gateway (true).
Possible Exceptions Meaning
BrokerInvalidClientException The BrokerAdminClient has been destroyed or disconnected.
BrokerNoPermissionException The BrokerAdminClient does not have permission to browse the Broker.
BrokerNotInClusterException The Broker is not a member of a cluster.
BrokerNullParameterException The cluster_name or broker_name parameter is null.
BrokerUnknownClusterException There is no gateway to the specified cluster from this client's Broker.
cluster_name The name of the cluster whose gateway security is to be set.
broker_name The name of the Broker in the specified remote cluster to which this Broker is connected.
webMethods Broker Administration Java API Programmer’s Guide Version 8.2 281
12 Java API Administration Reference
Sets the type of authentication and level of encryption used for the cluster gateway. The remote Broker that makes up the other half of the gateway should be properly configured for the new settings prior to changing the settings on the local Broker. The changes may take some time to take effect.
You can get the current settings by using getLocalClusterGateways() or getAllClusterGateways() methods. The auth_type value can be any of the AUTH_TYPE_* values. The encrypt_level value can be any of the BrokerConnectionDescriptor.ENCRYPT_LEVEL_* values.
Important! Use this method with care because changing the security setting may cause the gateway to become disconnected. For example, setting SSL authentication or encryption when the remote Broker is not configured for SSL will cause the gateway to become disconnected.
See also BrokerAdminClient.getAllClusterGateways and BrokerAdminClient.getLocalClusterGateways
setClusterGatewaySharedEventTypes
void setClusterGatewaySharedEventTypes( String cluster_name, String broker_name, BrokerSharedEventTypeInfo[] infos) throws BrokerException
auth_type The type of authentication to set for the gateway, specified as one of the AUTH_TYPE_* values defined by BrokerAdminClient.
encrypt_level The level of encryption to set for the gateway, specified as one of the ENCRYPT_LEVEL_* values defined by BrokerConnectionDescriptor, described in the webMethods Broker Client Java API Programmer’s Guide.
Possible Exceptions Meaning
BrokerInvalidClientException The BrokerAdminClient has been destroyed or disconnected.
BrokerNoPermissionException The BrokerAdminClient does not have permission to modify the Broker.
BrokerNotInClusterException The Broker to which this client is connected is not a member of a cluster.
BrokerNullParameterException The cluster_name or broker_name parameter is null.
BrokerOutOfRangeException The auth_type or encrypt_level parameter contains an invalid value.
BrokerUnknownClusterException There is no gateway to the specified cluster from this Broker.
282 webMethods Broker Administration Java API Programmer’s Guide Version 8.2
12 Java API Administration Reference
Sets the complete list of shared event types on for a cluster gateway. The is_synchronized field in each element of infos is ignored.
Note: To configure gateway event type sharing, first save the can-subscribe settings on both sides of the gateway and then save the can-publish settings. It is important to set the can-subscribe settings before the can-publish settings and to set them in separate invocations of this method.
The subscribe_filter variable in each element of infos can be set to a filter string to control the events which are forwarded through the gateway. If you do not want event filtering to take place across the gateway, this member must be set to a null string. See the webMethods Broker Client Java API Programmer’s Guide for complete information on event filtering
See BrokerSharedEventTypeInfo for more information.
cluster_name The name of the cluster whose shared event types are to be set.
broker_name The name of the Broker in specified remote cluster.
infos The shared event type information.
Possible Exceptions Meaning
BrokerInvalidClientException The BrokerAdminClient has been destroyed or disconnected
BrokerInvalidSubscriptionException A parse error was encountered in one of the elements contained in infos.
BrokerInvalidTypeDefException One or more of the event types is incompatible with the type definition on the remote Broker.
BrokerNoPermissionException The client does not have permission to modify the Broker.
BrokerNotInClusterException The Broker to which this client is connected is not part of a cluster.
BrokerNotRunningException The gateway connection is currently not open.
BrokerNullParameterException The cluster_name, broker_name, or infos parameter is null, or an element in infos is null, or an element in infos has a nullevent_type_name.
BrokerOutOfRangeException An event type in infos does not have accept_subscribe permission, but has a non-empty subscription_filter.
BrokerUnknownEventTypeException An element in infos does not exist on either Broker in the gateway. If this exception is thrown, no changes are applied.
webMethods Broker Administration Java API Programmer’s Guide Version 8.2 283
12 Java API Administration Reference
See Also:
BrokerAdminClient.getClusterGatewaySharedEventTypes
setClusterPrimaryGateway
public void setClusterPrimaryGateway( String cluster_name, String broker_name) throws BrokerException
Set the primary gateway connection from this Broker to the remote cluster specified by cluster_name and broker_name.
setClusterSecurity
void setClusterSecurity( int auth_type, int encrypt_level) throws BrokerException
BrokerUnknownClusterException There is no gateway to the specified cluster from the local Broker.
cluster_name The name of the cluster to which the primary gateway connection has to be set.
broker_name The name of the Broker in the specified cluster that will be used for the primary gateway connection.
Possible Exceptions Meaning
BrokerInvalidClientException The BrokerAdminClient has been destroyed or disconnected
BrokerNoPermissionException The client does not have permission to modify the Broker.
BrokerNotInClusterException The Broker to which this client is connected is not part of a cluster.
BrokerNullParameterException The cluster_name or broker_name parameter is null.
BrokerUnknownClusterException There is no gateway to the specified cluster from the local Broker.
BrokerIncompatibleVersionException The Broker does not support cluster gateways. Broker Server version 8.2 and above support cluster gateways.
Possible Exceptions Meaning
284 webMethods Broker Administration Java API Programmer’s Guide Version 8.2
12 Java API Administration Reference
Set the type of authentication and level of encryption used for the cluster. All Brokers in the cluster must be properly configured for the new settings and the changes may take some time to be propagated throughout the cluster.
Important! Use this method with care because changing the security setting may cause the cluster to become partially disconnected. For example, setting SSL authentication or encryption when one or more Brokers are not configured for SSL will cause the cluster to become partially disconnected.
See also BrokerAdminClient.getClusterInfo
setClusterStaticGatewayForwarding
void setClusterStaticGatewayForwarding( String cluster_name, String broker_name, boolean enable) throws BrokerException
Set whether to enable or disable a cluster gateway forwarding of shared documents across the gateway.
auth_type The type of authentication to set for the cluster, specified as one of the AUTH_TYPE_* values defined by BrokerAdminClient.
encrypt_level The level of encryption to set for the cluster, specified as one of the ENCRYPT_LEVEL_* values defined by BrokerConnectionDescriptor, described in the webMethods Broker Client Java API Programmer’s Guide.
Possible Exceptions Meaning
BrokerInvalidClientException The BrokerAdminClient has been destroyed or disconnected.
BrokerNoPermissionException The BrokerAdminClient does not have permission to modify the Broker.
BrokerNotInClusterException The Broker to which this client is connected is not part of a cluster.
BrokerOutOfRangeException The auth_type or encrypt_level parameter contains an invalid value.
cluster_name The name of the cluster to which you want to enable or disable static gateway forwarding.
broker_name The name of the Broker used to identify the correct gateway link for enabling or disabling static gateway forwarding.
enable Specify whether the cluster will have static gateway forwarding to the other cluster connected by a gateway. The default is true.
webMethods Broker Administration Java API Programmer’s Guide Version 8.2 285
12 Java API Administration Reference
setEventAdminTypeDef
void setEventAdminTypeDef( BrokerAdminTypeDef type_def) throws BrokerException
Sets the event type definition for the specified event type. If the event type does not exist on the Broker, it will be created.
See Also:
BrokerAdminClient.destroyEventType, BrokerAdminClient.destroyEventTypes, BrokerAdminClient.getEventAdminTypeDef, BrokerAdminClient.getEventAdminTypeDefs, BrokerAdminClient.getEventAdminTypeDefsByScope, and BrokerAdminClient.setEventAdminTypeDefs
setEventAdminTypeDefs
void setEventAdminTypeDefs( BrokerAdminTypeDef type_defs[]) throws BrokerException
Sets the event type definition for each of the event types specified in the type_defs array. If an event type in the array does not exist on the Broker, it will be created.
Possible Exceptions Meaning
BrokerInvalidClientException The BrokerAdminClient has been destroyed or disconnected
BrokerNotInClusterException The Broker to which this client is connected is not a member of a cluster.
BrokerNullParameterException The cluster_name or broker_name parameter is null.
BrokerUnknownClusterException There is no gateway to the specified cluster from the local Broker.
type_def A BrokerAdminTypeDef object containing the event type definition to be set.
Possible Exceptions Meaning
BrokerInvalidClientException The BrokerAdminClient has been destroyed or disconnected.
BrokerNoPermissionException The BrokerAdminClient does not have permission to modify the event type's definition or, if the event type is new, to create a new event type definition.
BrokerNullParameterException The type_def parameter is null.
type_defs An array of BrokerAdminTypeDef objects, each element containing an event type definition to be set.
286 webMethods Broker Administration Java API Programmer’s Guide Version 8.2
12 Java API Administration Reference
Note: If any entry in type_defs is found to be null, no event type definition will be set or modified.
See Also:
BrokerAdminClient.destroyEventType, BrokerAdminClient.destroyEventTypes, BrokerAdminClient.getEventAdminTypeDef, BrokerAdminClient.getEventAdminTypeDefs, BrokerAdminClient.getEventAdminTypeDefsByScope, and BrokerAdminClient.setEventAdminTypeDef
setEventLogging
void setEventLogging( boolean enabled) throws BrokerException
This method allows you to enable or disable event logging on each Broker. If enable_event_log is false(0), logging will be disabled. No events will be logged. If enable_event_log is true(1), logging will be enabled. Events published and acknowledged will be logged.
setEventTypeInfoset
void setEventTypeInfoset( String event_type_name, String infoset_name, BrokerEvent infoset) throws BrokerException
Sets the infoset for the specified event type. The infoset is passed as a BrokerEvent, for convenience. If the infoset does not currently exist on the Broker, it will be created.
Note: For information on infoset name and infoset field name restrictions, see the webMethods Broker Client Java API Programmer’s Guide.
Possible Exceptions Meaning
BrokerInvalidClientException The BrokerAdminClient has been destroyed or disconnected.
BrokerNoPermissionException The BrokerAdminClient does not have permission to modify the event type's definition or, if the event type is new, to create a new event type definition.
BrokerNullParameterException The type_defs parameter is null or any array entry is null.
event_type_name The event type with which the infoset is associated.
infoset_name The name of the infoset to set. If null, the type name of the event will be used as the infoset name.
infoset A BrokerEvent object which represents the infoset.
webMethods Broker Administration Java API Programmer’s Guide Version 8.2 287
12 Java API Administration Reference
See Also:
BrokerAdminClient.destroyEventTypeInfoset, BrokerAdminClient.destroyEventTypeInfosets, and BrokerAdminClient.setEventTypeInfosets, as well as BrokerClient.getEventTypeInfoset and BrokerClient.getEventTypeInfoset (described in the webMethods Broker Client Java API Programmer’s Guide)
setEventTypeInfosets
void setEventTypeInfosets( String event_type_name, BrokerEvent infosets[]) throws BrokerException
Sets the infosets for the specified event type. The infosets are passed as an array of BrokerEvent objects, for convenience. The type name of the infoset events are used as the infoset names. If an infoset found in the array does not currently exist on the Broker, it will be created.
Note: Previously existing infosets will not be destroyed.
Possible Exceptions Meaning
BrokerInvalidClientException The BrokerAdminClient has been destroyed or disconnected.
BrokerInvalidEventTypeNameException The infoset_name is invalid.
BrokerNoPermissionException The BrokerAdminClient does not have permission to modify the event type's infoset.
BrokerNullParameterException The event_type_name parameter is null.
BrokerUnknownEventTypeException The event_type_name does not exist on the Broker.
event_type_name The event type with which the infoset is associated.
infosets An array of BrokerEvent objects which represent the infosets for the event type.
Possible Exceptions Meaning
BrokerInvalidClientException The BrokerAdminClient has been destroyed or disconnected.
BrokerNoPermissionException The BrokerAdminClient does not have permission to modify the event type's infosets.
BrokerNullParameterException The event_type_name or infosets parameter is null, or an entry in the infosets array is null.
288 webMethods Broker Administration Java API Programmer’s Guide Version 8.2
12 Java API Administration Reference
See Also:
BrokerAdminClient.destroyEventTypeInfoset, BrokerAdminClient.destroyEventTypeInfosets, and BrokerAdminClient.setEventTypeInfoset, as well as BrokerClient.getEventTypeInfoset and BrokerClient.getEventTypeInfoset (described in the webMethods Broker Client Java API Programmer’s Guide)
setEventTypesAndClientGroups
BrokerSetFailureInfo setEventTypesAndClientGroups( String event_type_names_to_destroy[], String client_group_names_to_destroy[], BrokerCompleteEventType event_types[], BrokerCompleteClientGroup client_groups[], boolean forced) throws BrokerException
With one invocation of this method, you can create, modify, and destroy both event types and client groups on the Broker to which this administrative client is connected. All deletions take place first, then all the other values are either created, if they did not exist, or they are modified.
This method returns null if all operations completed successfully. If an error occurs, the returned BrokerSetFailureInfo object will contain the details. If there are any permission problems, then only permission problems are reported. If there are no permission
BrokerUnknownEventTypeException The event_type_name does not exist on the Broker.
event_type_names_to_destroy A list of event types that are to be destroyed on the Broker. May be set to null if you do not wish to destroy any event types.
client_group_names_to_destroy A list of client groups that are to be destroyed on the Broker. May be set to null if you do not wish to destroy any client groups.
event_types A set of event types to be defined on the Broker. May be set to null if you do not wish to add or modify any event types.
client_groups A set of client group to be defined on the Broker. May be set to null if you do not wish to add or modify any client groups.
forced If set to false, any failure in destroying or adding either a client group or an event type will be reported in the return value and no changes will be made to the Broker. If set to true, failures may still be reported in the return value, but all changes that can be made to the Broker will be made.
Possible Exceptions Meaning
webMethods Broker Administration Java API Programmer’s Guide Version 8.2 289
12 Java API Administration Reference
problems, then only dependency failures are reported. If force is set to true, then as much work as possible is completed. Any permission errors will cause this method to fail. Any dependency problem will be forced if force is set to true.
Any of the first four arguments may be null if you do not wish to destroy, create, or modify an event type or client group.
If one of the event_types or client_groups elements specified already exists on the Broker, it will be updated with the new settings. If a variable in one of the event_types or client_groups elements is null, that aspect of the event type or client group will not be changed.
If the infosets variable in an event_types element is not null, the replace_all_infosets flag in that element will be used to determine if the infosets are merged in or if they completely replace the existing infosets.
To delete infosets using this method, you must obtain a list of the existing infosets, remove the ones you want to delete, and then set the replace_all_infosets flag to true.
See Also:
BrokerAdminClient.getEventAdminTypeDef, BrokerAdminClient.getEventAdminTypeDefs, BrokerAdminClient.getClientGroupInfo, BrokerAdminClient.getClientGroupInfos
Possible Exceptions Meaning
BrokerInvalidAccessListException An ACL, specified in one of the client_groups elements, is invalid.
BrokerInvalidClientException The BrokerAdminClient has been destroyed or disconnected.
BrokerInvalidClientGroupException A client group name, specified in one of the client_groups elements, is invalid.
BrokerInvalidEventTypeNameException An event type name, specified in one of the event_types elements, is invalid.
BrokerNullParameterException An element in event_types or client_groups is null, or a BrokerCompleteEventTypetype_def field is null, or a BrokerCompleteClientGroupclient_group_info field is null, of the name field in a client_group_info is null.
BrokerOutOfRangeException An element in client_groups specifies an invalid life_cycle or storage_type value.
BrokerUnknownEventTypeException An element in client_groups specified an unknown event type name in a client group's can-publish or can-subscribe list.
290 webMethods Broker Administration Java API Programmer’s Guide Version 8.2
12 Java API Administration Reference
setPostPrepareTimeout
void setPostPrepareTimeout( int timeout_secs) throws BrokerException
Specifies the default value, in seconds, of the post-prepare time-out period. The post-prepare time-out period is the period of time between the point when a transaction is prepared and when it is committed.
See Also:
BrokerAdminClient.getPostPrepareTimeout and BrokerAdminClient.setPostPrepareTimeoutAction
setPostPrepareTimeoutAction
void setPostPrepareTimeoutAction( int action) throws BrokerException
Specifies whether the Broker transaction manager is to rollback or commit prepared transactions when they exceed the allotted post-prepare time-out period. The post-prepare time-out period is the period of time between the point when a transaction is prepared and when it is committed.
timeout_secs The post-prepare timeout in seconds.
Possible Exceptions Meaning
BrokerInvalidClientException The BrokerAdminClient has been destroyed or disconnected.
BrokerNoPermissionException The BrokerAdminClient does not have permission to modify the Broker.
BrokerOutOfRangeException The timeout_secs value is out of range.
BrokerIncompatibleVersionException The Broker does not support transaction administration.
action BrokerAdminClient.TRANSACTION_ROLLBACK or BrokerAdminClient.TRANSACTION_COMMIT.
Possible Exceptions Meaning
BrokerInvalidClientException The BrokerAdminClient has been destroyed or disconnected.
BrokerNoPermissionException The BrokerAdminClient does not have permission to modify the Broker.
BrokerOutOfRangeException The value of action is invalid.
webMethods Broker Administration Java API Programmer’s Guide Version 8.2 291
12 Java API Administration Reference
See Also:
BrokerAdminClient.getPostPrepareTimeoutAction and BrokerAdminClient.setPostPrepareTimeout
setPrePrepareTimeout
void setPrePrepareTimeout( int timeout_secs) throws BrokerException
Specifies the default value, in seconds, of the pre-prepare time-out period. The pre-prepare time-out period is the period of time between the point when a transaction begins until it is asked to prepare.
See Also:
BrokerAdminClient.getPrePrepareTimeout
setRecoverMode
void setRecoverMode(int mode) throws BrokerException
Specifies the recover mode for Broker transaction manager. The recover mode setting determines whether clients are permitted to recover any recoverable transactions (RECOVER_GLOBAL) or only those transaction in which they participated (RECOVER_RESTRICTED).
BrokerIncompatibleVersionException The Broker does not support transaction administration.
timeout_secs The pre-prepare timeout in seconds.
Possible Exceptions Meaning
BrokerInvalidClientException The BrokerAdminClient has been destroyed or disconnected.
BrokerNoPermissionException The BrokerAdminClient does not have permission to modify the Broker.
BrokerOutOfRangeException The timeout_secs value is out of range.
BrokerIncompatibleVersionException The Broker does not support transaction administration.
mode RECOVER_RESTRICTED or RECOVER_GLOBAL.
Possible Exceptions Meaning
292 webMethods Broker Administration Java API Programmer’s Guide Version 8.2
12 Java API Administration Reference
See Also:
BrokerAdminClient.getRecoverMode
setRemoteBrokerKeepAlive
int setRemoteBrokerKeepAlive( String broker_name, int KeepAlive) throws BrokerException
This method enables or disables the keep-alive feature on the remote Broker. When enabled, the remote Broker issues 'keep-alive' messages to the Broker specified in Broker-name. Both Brokers must belong to the same territory.
The keep-alive feature is useful when the firewalls separating Brokers are programmed to drop connections that are idle for extended periods. To prevent the firewall from dropping the connection between the Brokers, you use the keep-alive feature to generate enough traffic to keep the connection alive.
Setting KeepAlive to a positive number instructs the remote Broker to issue keep-alive messages when its connection to broker_name is idle longer than the KeepAlive period (in seconds).
Possible Exceptions Meaning
BrokerInvalidClientException The BrokerAdminClient has been destroyed or disconnected.
BrokerNoPermissionException The BrokerAdminClient does not have permission to modify the Broker.
BrokerOutOfRangeException The timeout_secs value is out of range.
broker_name The name of the Broker to which you want the remote Broker to issue keep-alive messages.
KeepAlive The frequency, in number of seconds, with which the remote Broker will issue keep-alive messages to broker_name. Set KeepAlive to 0 to disable keep-alive messages.
Possible Exceptions Meaning
BrokerInvalidClientException The BrokerAdminClient has been destroyed or disconnected
BrokerNullParameterException broker_name is null
BrokerOutOfRageException KeepAlive value is < 0.
BrokerIncompatibleVersionException A Broker does not support the keep-alive feature.
webMethods Broker Administration Java API Programmer’s Guide Version 8.2 293
12 Java API Administration Reference
For more information, see “Maintaining a Connection Between Brokers in a Territory” on page 96.
See also BrokerAdminClient.getRemoteBrokerKeepAlive
setStaticGatewayForwarding
void setStaticGatewayForwarding( String territory_name, boolean enable) throws BrokerException
Specifies if static gateway forwarding is enabled or disabled. Set to true to enable static gateway forwarding; set to false to disable.
Note: The default value of setStaticGatewayForwarding is version-dependent. Static gateway forwarding was introduced in version 6.5. For that version and later, the default value is true and static gateway forwarding is enabled.
See Also:
BrokerAdminClient.getStaticGatewayForwarding
setTerritoryACL
void setTerritoryACL( BrokerAccessControlList acl) throws BrokerException
Sets the access control list used by Broker's in this territory to accept connections from other Brokers in the territory. Changing the territory's ACL will not cause existing inter-Broker connections to fail.
For more information on territories, see “Managing Broker Territories” on page 93.
territory_name name of the remote territory
enable state of static gateway forwarding
Possible Exceptions Meaning
BrokerIncompatibleVersionException The gateway Broker on which the static forwarding option is applied to is an earlier version than webMethods Broker version 6.5.
BrokerNotInTerritoryException The gateway Broker is not in the territory.
BrokerNullParameterException territory_name is full.
BrokerUnknownTerritoryException On the current Broker, there is no local gateway to the specified remote territory.
acl The access control list to set for this Broker's territory.
294 webMethods Broker Administration Java API Programmer’s Guide Version 8.2
12 Java API Administration Reference
Important! If you use this method to disallow a user identity that is currently being used by a member of the territory, your territory will become partially disconnected.
See Also:
BrokerAdminClient.getTerritoryACL
setTerritoryGatewayACL
void setTerritoryGatewayACL( String territory_name, BrokerAccessControlList acl) throws BrokerException
Set the access control list that the Broker to which this client is connected will use to accept connections from the remote Broker in the territory gateway.
The access control list can contain either one entry or no entries in each of the user and authenticator lists. Changing the current access control list will not cause an existing gateway connection to fail.
Important! If you use this method to disallow a user identity that is currently being used by the other Broker in the territory gateway, the gateway will become disconnected.
Possible Exceptions Meaning
BrokerInvalidAccessListException The acl variable does not contain a valid access control list.
BrokerInvalidClientException The BrokerAdminClient has been destroyed or disconnected.
BrokerNoPermissionException The BrokerAdminClient does not have permission to modify the Broker.
BrokerNotInTerritoryException The Broker to which this client is connected is not part of a territory.
BrokerNullParameterException The acl parameter is null.
territory_name The name of the territory whose gateway ACL is to be set.
acl The access control list to set for this Broker's territory.
Possible Exceptions Meaning
BrokerInvalidAccessListException The acl variable does not contain a valid access control list.
BrokerInvalidClientException The BrokerAdminClient has been destroyed or disconnected.
webMethods Broker Administration Java API Programmer’s Guide Version 8.2 295
12 Java API Administration Reference
See Also:
BrokerAdminClient.getTerritoryGatewayACL
setTerritoryGatewayKeepAlive
void setTerritoryGatewayKeepAlive( String territory_name, int KeepAlive) throws BrokerException
This method enables or disables the keep-alive feature on the gateway Broker. When enabled, the gateway Broker issues 'keep-alive' messages to the territory specified in territory-name.
The keep-alive feature is useful when the firewalls separating gateway Brokers are programmed to drop connections that are idle for extended periods. To prevent the firewall from dropping the connection between the gateway Brokers, you use the keep-alive feature to generate enough traffic to keep the connection alive.
BrokerNoPermissionException The BrokerAdminClient does not have permission to modify the Broker.
BrokerNotInTerritoryException The Broker to which this client is connected is not part of a territory.
BrokerNullParameterException The acl parameter is null.
BrokerOutOfRangeException The acl contains more than one user entry or more than one authenticator entry.
BrokerUnknownTerritoryException There is no gateway to the specified territory from this Broker.
territory_name The name of the territory to which you want the gateway Broker to issue keep-alive messages.
KeepAlive The frequency, in number of seconds, with which the gateway Broker will issue keep-alive messages to territory_name. Set KeepAlive to 0 to disable keep-alive messages.
Possible Exceptions Meaning
BrokerInvalidClientException The BrokerAdminClient has been destroyed or disconnected
BrokerNullParameterException territory_name is null
BrokerOutOfRageException KeepAlive value is < 0.
BrokerIncompatibleVersionException Gateway Broker does not support the keep-alive feature.
Possible Exceptions Meaning
296 webMethods Broker Administration Java API Programmer’s Guide Version 8.2
12 Java API Administration Reference
Setting KeepAlive to a positive number instructs the gateway Broker to issue keep-alive messages when its connection to territory_name is idle longer than the KeepAlive period (in seconds).
For more information about the keep-alive feature, see “Maintaining a Connection Between Gateway Brokers” on page 100.
See also BrokerAdminClient.getTerritoryGatewayKeepAlive
setTerritoryGatewayPause
void setTerritoryGatewayPause( String territory_name, boolean pause) throws BrokerException
This methods prevents the gateway Broker from forwarding events to the territory in territory_name. Once the gateway has been paused, the gateway Broker will hold events for the specified territory until the pause state is explicitly cleared by setting pause to false.
To check whether outbound events to another territory have been are paused, check the gateway_pause value returned by getTerritoryGatewayStats.
territory_name The name of the territory whose events you want the gateway Broker to hold.
pause Flag indicating whether the gateway Broker is to pause or resume the transmission of events to the territory in territory_name. Set to true to halt the forwarding of events to territory_name. Set to false to resume sending events to territory_name.
Possible Exceptions Meaning
BrokerInvalidClientException The BrokerAdminClient has been destroyed or disconnected.
BrokerNullParameterException territory_name is null.
BrokerBadStateException The territory gateway is already paused or resumed.
BrokerNoPermissionException The BrokerAdminClient does not have permission to modify the Broker.
BrokerNotInTerritoryException The Broker to which this client is connected is not a member of a territory.
BrokerUnknownTerritoryException There is no gateway to the specified territory from this Broker.
BrokerIncompatibleVersionException The gateway Broker does not support this feature.
webMethods Broker Administration Java API Programmer’s Guide Version 8.2 297
12 Java API Administration Reference
setTerritoryGatewayRefuseAllUpdates
public void setTerritoryGatewayRefuseAllUpdates( String territory_name) boolean refuse_updates) throws BrokerException
Set whether a territory gateway will refuse all updates to shared document types made in a connected territory.
If the refuse_updates parameter is set to true, all updates from the specified territory are refused, regardless of whether setTerritoryGatewayRefuseEventTypeUpdates is set to refuse updates to specific document types. However, the individual settings for each event type are retained, so that when refuse_updates parameter is set back to false, the original event type settings are reset.
See Also:
BrokerAdminClient.getTerritoryGatewayRefuseAllUpdates
setTerritoryGatewayRefuseEventTypeUpdates
public void setTerritoryGatewayRefuseEventTypeUpdates( String territory_name BrokerSharedEventTypeRefuseUpdateInfo[] infos) throws BrokerException
BrokerQueueBrowserException The gateway forwarding queue is locked by a queue browser.
territory_name The name of the territory to which updates are refused.
refuse_updates Specify whether the territory will refuse all updates from a neighboring territory connected by a gateway (true).
Possible Exceptions Meaning
BrokerInvalidClientException The BrokerAdminClient has been destroyed or disconnected.
BrokerNoPermissionException The BrokerAdminClient does not have permission to browse the Broker.
BrokerNotInTerritoryException The Broker is not a member of a territory.
BrokerNullParameterException The territory_name parameter is null.
BrokerUnknownTerritoryException There is no gateway to the specified territory from this client's Broker.
territory_name The name of the territory for which updates made in a neighboring territory are refused.
Possible Exceptions Meaning
298 webMethods Broker Administration Java API Programmer’s Guide Version 8.2
12 Java API Administration Reference
Set whether a Broker territory can refuse updates for a document type, when they originate from a neighboring territory connected by a gateway. Note that if setTerritoryGatewayRefuseEventTypeUpdates is set to true, then this method is ignored and all updates are refused.
See Also:
BrokerAdminClient.getTerritoryGatewayRefuseEventTypeUpdates
setTerritoryGatewaySecurity
void setTerritoryGatewaySecurity( String territory_name, int auth_type, int encrypt_level) throws BrokerException
Sets the type of authentication and level of encryption used for the territory gateway. The remote Broker that makes up the other half of the gateway should be properly configured for the new settings prior to changing the settings on the local Broker. The changes may take some time to take effect.
infos Specifies information about whether events and updates for a document type in a neighboring territory are refused.
Possible Exceptions Meaning
BrokerInvalidClientException The BrokerAdminClient has been destroyed or disconnected.
BrokerNoPermissionException The BrokerAdminClient does not have permission to browse the Broker.
BrokerNotInTerritoryException The Broker is not a member of a territory.
BrokerNullParameterException The territory_name parameter is null.
BrokerUnknownTerritoryException There is no gateway to the specified territory from this client's Broker.
territory_name The name of the territory whose gateway security is to be set.
auth_type The type of authentication to set for the gateway, specified as one of the AUTH_TYPE_* values defined by BrokerAdminClient.
encrypt_level The level of encryption to set for the gateway, specified as one of the ENCRYPT_LEVEL_* values defined by BrokerConnectionDescriptor, described in the webMethods Broker Client Java API Programmer’s Guide.
webMethods Broker Administration Java API Programmer’s Guide Version 8.2 299
12 Java API Administration Reference
Important! Use this method with care because changing the security setting may cause the gateway to become disconnected. For example, setting SSL authentication or encryption when the remote Broker is not configured for SSL will cause the gateway to become disconnected.
See also BrokerAdminClient.getAllClusterGateways and BrokerAdminClient.getLocalClusterGateways
setTerritoryGatewaySharedEventTypes
void setTerritoryGatewaySharedEventTypes( String territory_name, BrokerSharedEventTypeInfo infos[]) throws BrokerException
Sets the complete list of shared event types on for a territory gateway. The is_synchronized field in each element of infos is ignored.
Note: To configure gateway event type sharing, first save the can-subscribe settings on both sides of the gateway and then save the can-publish settings. It is important to set the can-subscribe settings before the can-publish settings and to set them in separate invocations of this method.
The subscribe_filter variable in each element of infos can be set to a filter string to control the events which are forwarded through the gateway. If you do not want event filtering to take place across the gateway, this member must be set to a null string. See the webMethods Broker Client Java API Programmer’s Guide for complete information on event filtering
See BrokerSharedEventTypeInfo for more information.
Possible Exceptions Meaning
BrokerInvalidClientException The BrokerAdminClient has been destroyed or disconnected.
BrokerNoPermissionException The BrokerAdminClient does not have permission to modify the Broker.
BrokerNotInTerritoryException The Broker to which this client is connected is not part of a territory.
BrokerNullParameterException The territory_name parameter is null.
BrokerOutOfRangeException The auth_type or encrypt_level parameter contains an invalid value.
BrokerUnknownTerritoryException There is no gateway to the specified territory from this Broker.
territory_name The name of the territory whose shared event types are to be set.
infos The shared event type information.
300 webMethods Broker Administration Java API Programmer’s Guide Version 8.2
12 Java API Administration Reference
See Also:
BrokerAdminClient.getTerritoryGatewaySharedEventTypes
setTerritorySecurity
void setTerritorySecurity( int auth_type, int encrypt_level) throws BrokerException
Possible Exceptions Meaning
BrokerInvalidClientException The BrokerAdminClient has been destroyed or disconnected
BrokerInvalidSubscriptionException A parse error was encountered in one of the elements contained in infos.
BrokerInvalidTypeDefException One or more of the event types is incompatible with the type definition on the remote Broker.
BrokerNoPermissionException The client does not have permission to modify the Broker.
BrokerNotInTerritoryException The Broker to which this client is connected is not part of a territory.
BrokerNotRunningException The gateway connection is currently not open.
BrokerNullParameterException The territory_name or infos parameter is null, or an element in infos is null, or an element in infos has a nullevent_type_name.
BrokerOutOfRangeException An event type in infos does not have accept_subscribe permission, but has a non-empty subscription_filter.
BrokerUnknownEventTypeException An element in infos does not exist on either Broker in the gateway. If this exception is thrown, no changes are applied.
BrokerUnknownTerritoryException There is no gateway to the specified territory from the local Broker.
auth_type The type of authentication to set for the territory, specified as one of the AUTH_TYPE_* values defined by BrokerAdminClient.
encrypt_level The level of encryption to set for the territory, specified as one of the ENCRYPT_LEVEL_* values defined by BrokerConnectionDescriptor, described in the webMethods Broker Client Java API Programmer’s Guide.
webMethods Broker Administration Java API Programmer’s Guide Version 8.2 301
12 Java API Administration Reference
Set the type of authentication and level of encryption used for the territory. All Brokers in the territory must be properly configured for the new settings and the changes may take some time to be propagated throughout the territory.
Important! Use this method with care because changing the security setting may cause the territory to become partially disconnected. For example, setting SSL authentication or encryption when one or more Brokers are not configured for SSL will cause the territory to become partially disconnected.
See also BrokerAdminClient.getTerritoryInfo
BrokerAdminTypeDef
class BrokerAdminTypeDef extends java.lang.object
This class is used by BrokerAdminClient objects to administer the event type definitions stored by a Broker. It provides methods for administering a Broker's BrokerTypeDef object.
Many of the methods offered by this class make use of these BrokerTypeDef constants, described in the webMethods Broker Client Java API Programmer’s Guide.
The following table shows the BrokerTypeDef constants for each field type.
Possible Exceptions Meaning
BrokerInvalidClientException The BrokerAdminClient has been destroyed or disconnected.
BrokerNoPermissionException The BrokerAdminClient does not have permission to modify the Broker.
BrokerNotInTerritoryException The Broker to which this client is connected is not part of a territory.
BrokerOutOfRangeException The auth_type or encrypt_level parameter contains an invalid value.
BrokerTypeDef Data Members 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_FLOAT Represents a float.
short FIELD_TYPE_INT Represents a int.
302 webMethods Broker Administration Java API Programmer’s Guide Version 8.2
12 Java API Administration Reference
Constructors
BrokerAdminTypeDef
BrokerAdminTypeDef( BrokerTypeDef normal_def) throws BrokerException
Creates a copy of a normal type definition.
BrokerAdminTypeDef
BrokerAdminTypeDef( BrokerAdminTypeDef type_def) throws BrokerException
Copy constructor.
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_UNKNOWN Represents a unknown field type.
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
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.
normal_def The BrokerTypeDef that this object is to administer.
Possible Exceptions Meaning
BrokerNullParameterException The parameter normal_def parameter is null.
type_def The object being copied.
BrokerTypeDef Data Members Description
webMethods Broker Administration Java API Programmer’s Guide Version 8.2 303
12 Java API Administration Reference
BrokerAdminTypeDef
BrokerAdminTypeDef( short type) throws BrokerException
Creates a new type definition for a non-event type with no name. Use this constructor when you want to create a BrokerAdminTypeDef object that represents an event field definition for use with the BrokerAdminTypeDef.setFieldDef method.
BrokerAdminTypeDef
BrokerAdminTypeDef( String type_name, short type) throws BrokerException
Creates a new type definition with the specified name and type.
Note: For information on event type name restrictions, see the webMethods Broker Client Java API Programmer’s Guide.
Possible Exceptions Meaning
BrokerNullParameterException The parameter type_def parameter is null.
type The field type being created. You can use any of the values listed in the table in BrokerAdminTypeDef except FIELD_TYPE_EVENT.
Possible Exceptions Meaning
BrokerInvalidTypeException The type is FIELD_TYPE_EVENT or an invalid value.
type_name The name of the type being created.
type The type being created. Must be either FIELD_TYPE_EVENT or FIELD_TYPE_STRUCT.
Possible Exceptions Meaning
BrokerInvalidEventTypeNameException The type_name is invalid.
BrokerInvalidTypeException The type is not FIELD_TYPE_EVENT or a FIELD_TYPE_STRUCT.
BrokerNullParameterException The parameter type_name parameter is null and type is FIELD_TYPE_EVENT.
304 webMethods Broker Administration Java API Programmer’s Guide Version 8.2
12 Java API Administration Reference
Methods
clearField
void clearField( String field_name) throws BrokerException
Removes the specified field name from the event type definition.
See Also:
BrokerAdminTypeDef.clearFields
clearFields
void clearFields()
Deletes all fields from the event type definition.
clearModificationFlag
void clearModificationFlag()
Sets the modification flag for the event type definition such that subsequent invocations of the BrokerTypeDef.hasBeenModified method will return false.
See:
BrokerAdminTypeDef.hasBeenModified and BrokerAdminTypeDef.setModificationFlag
getBaseTypeName
String getBaseTypeName()
field_name The name of the event field to be removed from the definition.
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.
BrokerInvalidTypeException The field is not a field in a struct or event type.
BrokerNullParameterException The field_name parameter is null.
Possible Exceptions Meaning
BrokerInvalidTypeException This object is not a struct or event type.
webMethods Broker Administration Java API Programmer’s Guide Version 8.2 305
12 Java API Administration Reference
Returns the name of the event type definition without the scope qualifier.
See:
BrokerAdminTypeDef.getFieldDef, BrokerAdminTypeDef.getTypeName, and BrokerAdminTypeDef.setTypeName
getDescription
String getDescription() throws BrokerException
Returns the description for this event type definition.
See Also:
BrokerAdminTypeDef.setDescription
getFieldDef
BrokerAdminTypeDef getFieldDef( String field_name) throws BrokerException
Returns a BrokerAdminTypeDef containing the field definition for the specified field name.
See Also:
BrokerAdminTypeDef.getFieldNames, BrokerAdminTypeDef.getFieldType, BrokerAdminTypeDef.setFieldDef, and BrokerAdminTypeDef.setFieldType
getFieldNames
String[] getFieldNames( String field_name) throws BrokerException
Possible Exceptions Meaning
BrokerInvalidTypeException This object's type is not FIELD_TYPE_EVENT.
field_name The name of the field whose definition is to be returned.
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 parameter field_name not valid.
306 webMethods Broker Administration Java API Programmer’s Guide Version 8.2
12 Java API Administration Reference
Returns an array of strings containing the names of the fields in an event type or structure field. If field_name is set to a non-structure field, null will be returned.
See Also:
BrokerAdminTypeDef.getFieldDef and BrokerAdminTypeDef.getFieldType
getFieldType
short getFieldType( String field_name) throws BrokerException
Returns the type of the event or the field with the specified field_name. See the table in BrokerAdminTypeDef for a list of possible return values.
See Also:
BrokerAdminTypeDef.getFieldDef, BrokerAdminTypeDef.setFieldDef, and BrokerAdminTypeDef.setFieldType
getScopeTypeName
String getScopeTypeName()
Returns this event type's scope name.
field_name If set to null or contains a null string, all of the fields at the top level of the event definition will be returned. Otherwise, this should be set to the name of a structure field.
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.
field_name If set to null, the event's type is returned. Otherwise, the type of the specified field is returned.
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.
webMethods Broker Administration Java API Programmer’s Guide Version 8.2 307
12 Java API Administration Reference
See:
BrokerAdminTypeDef.getBaseTypeName, BrokerAdminTypeDef.getTypeName, and BrokerAdminTypeDef.setTypeName
getStorageType
int getStorageType() throws BrokerException
Returns the storage type for the event as one of the values described in the table in BrokerAdminTypeDef.
See Also:
BrokerAdminTypeDef.setStorageType
getTimeToLive
int getTimeToLive() throws BrokerException
Returns the number of seconds that the event type will be available after being published, before it expires and is destroyed. A value of zero indicates the event will never expire.
See Also:
BrokerAdminTypeDef.setTimeToLive
getTypeName
String getTypeName()
Returns the fully-qualified name of this event type.
See:
BrokerAdminTypeDef.getBaseTypeName, BrokerAdminTypeDef.getFieldDef, and BrokerAdminTypeDef.setTypeName
hasBeenModified
boolean hasBeenModified()
Returns true if this event type has been modified. Otherwise, false is returned.
Possible Exceptions Meaning
BrokerInvalidTypeException The type of this object is not FIELD_TYPE_EVENT.
Possible Exceptions Meaning
BrokerInvalidTypeException The type of this object is not FIELD_TYPE_EVENT.
308 webMethods Broker Administration Java API Programmer’s Guide Version 8.2
12 Java API Administration Reference
See:
BrokerAdminTypeDef.clearModificationFlag, and BrokerAdminTypeDef.setModificationFlag
insertFieldDef
void insertFieldDef( String field_name, int index, BrokerAdminTypeDef field_def) throws BrokerException
Inserts a new event field with the specified field_name and definition. If the field currently exists, its position and definition are updated.
Note: For information on event field name restrictions, see the webMethods Broker Client Java API Programmer’s Guide.
Specifying an index of 0 will position the field at the top of the list of event fields. Specifying an index greater than the number of event fields will position the field at the end of the list.
If field_name is null or contains a null string, this method will operate on this object.
See Also:
BrokerAdminTypeDef.getFieldDef and BrokerAdminTypeDef.setFieldDef
isSystemDefined
boolean isSystemDefined()
field_name The name of the field to be added or moved.
index The offset within the event where the field is to be positioned. The field will be inserted before the field with the specified index.
field_def The type definition for the field being added or moved.
Possible Exceptions Meaning
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's type is not FIELD_TYPE_EVENT or FIELD_TYPE_STRUCT.
BrokerNullParameterException The field_def parameter is null.
BrokerOutOfRangeException The index is less than zero.
webMethods Broker Administration Java API Programmer’s Guide Version 8.2 309
12 Java API Administration Reference
Returns true if this event type is a system-defined type, otherwise false is returned.
Note: Only the infoset for system-defined event types may be altered. Other properties associated with system-defined event types; such as type definition, storage type, and time-to-live; may not be changed.
orderFields
void orderFields( String field_name, String new_field_names[]) throws BrokerException
Sets the order of the fields contained in field_name to the order specified in new_field_names. Any fields which are not in the new_field_names list are left in their current position, following the re-ordered fields.
See Also:
BrokerAdminTypeDef.getFieldNames
renameField
void renameField( String old_field_name, String new_field_name) throws BrokerException
field_name The name of the field whose fields are to be reordered. If set to null or to a null string, the top level of the event type definition is manipulated.
new_field_names An array of field names, specified in the order in which they are to appear in the field.
Possible Exceptions Meaning
BrokerFieldNotFoundException The specified field_name or any of the entries in new_field_names 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.
BrokerInvalidTypeException The field's type is not FIELD_TYPE_EVENT or FIELD_TYPE_STRUCT.
BrokerNullParameterException The new_field_names parameter is null or one of its entries is null.
old_field_name The name of a field to be renamed.
310 webMethods Broker Administration Java API Programmer’s Guide Version 8.2
12 Java API Administration Reference
Renames the administrative type definition field specified by old_field_name to new_field_name. See the webMethods Broker Client Java API Programmer’s Guide for complete information on specifying field names.
Note: For information on event field name restrictions, see the webMethods Broker Client Java API Programmer’s Guide.
See Also:
BrokerAdminTypeDef.clearField and BrokerAdminTypeDef.clearFields
setDescription
void setDescription( String description) throws BrokerException
Sets the description for the event type definition.
See Also:
BrokerAdminTypeDef.getDescription
new_field_name The new field name.
Possible Exceptions Meaning
BrokerFieldNotFoundException The specified old_field_name does not exist in the event.
BrokerFieldTypeMismatchException The old_field_name incorrectly accesses a type, such as using a subscript with a non-sequence field.
BrokerInvalidFieldNameException The old_field_name or new_field_name is invalid.
BrokerInvalidTypeException The old_field_name or new_field_name parameter does not refer to a named field. For example, a subscripted field like x[0] is not considered a named field.
BrokerNullParameterException The old_field_name or new_field_name parameter is null.
description The description to set for the event type definition.
Possible Exceptions Meaning
BrokerInvalidTypeException This object's type is not FIELD_TYPE_EVENT.
BrokerNullParameterException The description parameter is null.
webMethods Broker Administration Java API Programmer’s Guide Version 8.2 311
12 Java API Administration Reference
setFieldDef
void setFieldDef( String field_name, BrokerAdminTypeDef field_def) throws BrokerException
Sets the type definition of the specified field_name. If the specified field does not exist, it will be created.
Note: For information on event field name restrictions, see the webMethods Broker Client Java API Programmer’s Guide.
See Also:
BrokerAdminTypeDef.getFieldDef, BrokerAdminTypeDef.orderFields, and BrokerAdminTypeDef.setFieldType
setFieldType
void setFieldType( String field_name, short field_type, String type_name) throws BrokerException
Sets the type of the specified field_name. If the field does not exist in the event type, it is created.
field_name The name of the field whose definition is being set.
field_def The new type definition for the field.
Possible Exceptions Meaning
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 or field_def parameter is null.
field_name The name of the field whose definition is being set.
field_type The field's type, defined as one of the values shown in the table in BrokerAdminTypeDef.
type_name Currently not used and should be set to null.
Possible Exceptions Meaning
BrokerFieldTypeMismatchException The field_name incorrectly accesses a type, such as using a subscript with a non-sequence field.
312 webMethods Broker Administration Java API Programmer’s Guide Version 8.2
12 Java API Administration Reference
See Also:
BrokerAdminTypeDef.getFieldDef, BrokerAdminTypeDef.getFieldType, and BrokerAdminTypeDef.setFieldDef
setModificationFlag
void setModificationFlag()
Sets the modification flag for the type definition to true.
See:
BrokerAdminTypeDef.clearModificationFlag and BrokerAdminTypeDef.hasBeenModified
setStorageType
void setStorageType( int storage_type) throws BrokerException
Sets the storage type for the event type definition.
See Also:
BrokerAdminTypeDef.getStorageType
setTimeToLive
void setTimeToLive( int time_to_live) throws BrokerException
BrokerInvalidFieldNameException The field_name is invalid.
BrokerInvalidTypeException An attempt was made to change a field's type to FIELD_TYPE_SEQUENCE.
BrokerNullParameterException The field_name parameter is null.
storage_type The new storage type for the event type definition. Must be one of the following values:
BrokerTypeDef.STORAGE_GUARANTEED
BrokerTypeDef.STORAGE_VOLATILE
Possible Exceptions Meaning
BrokerInvalidTypeException This object's type is invalid.
BrokerOutOfRangeException The storage_type parameter is invalid.
Possible Exceptions Meaning
webMethods Broker Administration Java API Programmer’s Guide Version 8.2 313
12 Java API Administration Reference
Sets the number of seconds an event will be available after being published before it expires and is destroyed.
See Also:
BrokerAdminTypeDef.getTimeToLive
setTypeName
void setTypeName( String type_name) throws BrokerException
Sets the fully-qualified name for the event type.
Note: For information on event field name restrictions, see the webMethods Broker Client Java API Programmer’s Guide.
See Also:
BrokerAdminTypeDef.getTypeName.
toString
String toString()
Returns a string containing the type definition administration object in a human-readable format.
time_to_live The number of seconds after an event is published before it expires. A value of 0 denotes the event will never expire.
Possible Exceptions Meaning
BrokerInvalidTypeException This object's type not FIELD_TYPE_EVENT.
BrokerOutOfRangeException The time_to_live parameter is less than zero.
type_name The new, fully-qualified name for the event type.
Possible Exceptions Meaning
BrokerInvalidEventTypeNameException This object's type not FIELD_TYPE_EVENT.
BrokerInvalidTypeException The type is not FIELD_TYPE_STRUCT or FIELD_TYPE_EVENT
BrokerNullParameterException The type_name parameter is null.
314 webMethods Broker Administration Java API Programmer’s Guide Version 8.2
12 Java API Administration Reference
toString
String toString( int indent_level
Returns a string containing the type definition administration object in a human-readable format.
BrokerAuthInfo
class BrokerAuthInfo extends java.lang.Object
This class represents the authentication information for a client session.
If the client session uses basic authentication protocol, this class contains the username and authenticator alias information. If the client session uses SSL protocol, this class contains the distinguished name of the client and the distinguished name of the authenticator.
Variables
username
String username
For basic authentication protocol, contains the client’s basic authentication username. For SSL protocol, contains the client’s distinguished name.
authenticator
String authenticator
For basic authentication protocol, contains the authenticator alias. For SSL protocol, contains the issuer’s distinguished name.
Constructors
BrokerAuthInfo
BrokerAuthInfo()
Creates an empty BrokerAuthInfo object.
indent_level The number of 4-space indentations that should be generated in the output.
webMethods Broker Administration Java API Programmer’s Guide Version 8.2 315
12 Java API Administration Reference
BrokerAuthInfo
BrokerAuthInfo( String username, String authenticator)
Creates a BrokerAuthInfo object, initialized with the specified parameters.
BrokerAuthInfo
public BrokerAuthInfo( final BrokerAuthInfo source)
Creates a BrokerAuthInfo object initialized with the data from the source object.
Methods
getAuthenticator
public String getAuthenticator()
Returns the client program’s authenticator alias for a basic authentication connection, or returns the issuer’s distinguished name for an SSL connection.
getUserName
public String getUserName()
Returns the client program’s authentication username for a basic authentication connection, or returns the client program’s distinguished name for an SSL connection.
setAuthenticator
public void setAuthenticator( final String authenticator)
Sets the client program’s authenticator alias for a basic authentication connection, or sets the issuer’s distinguished name for an SSL connection.
setUserName
public void setUserName( final String userName)
Sets the client program’s authentication username for a basic authentication connection, or sets the client program’s distinguished name for an SSL connection.
username The Broker client’s username or distinguished name.
authenticator The authenticator alias or the issuer’s distinguished name.
source An existing instance of the BrokerAuthInfo object.
316 webMethods Broker Administration Java API Programmer’s Guide Version 8.2
12 Java API Administration Reference
toString
String toString()
Returns a human-readable string that contains the authentication information.
toString
String toString( int indent_level)
Returns a human-readable string that contains the authentication information. See also BrokerClientSession.auth_info.
BrokerChangeLockInfo
class BrokerChangeLockInfo
This class represents the information about a lock held by an administrative client for a Broker.
Variables
acquired
boolean acquired
Indicates whether or not this client has successfully acquired a lock for its Broker.
client_id
String client_id
If acquired is set to 0 (false), this variable will contain the identifier of the client that currently holds the lock for the Broker. If acquired is 1 (true), this variable will be set to null.
session_id
int session_id
If acquired is set to 0 (false), this variable will contain the session identifier of the client that currently holds the lock for the Broker. If acquired is 1 (true), this variable will be set to zero.
indent_level The number of four-space indentations that should be generated in the output.
webMethods Broker Administration Java API Programmer’s Guide Version 8.2 317
12 Java API Administration Reference
lock_time
BrokerDate lock_time
If acquired is set to 0 (false), this variable will contain the date and time that the lock for the Broker was acquired. If acquired is 1 (true), this variable will be set to null.
BrokerClientGroupInfo
class BrokerClientGroupInfo extends java.lang.Object
This class represents the client group information that is maintained by a Broker for each client group that is defined.
Variables
access_label_required
boolean access_label_required
Indicates whether or not an access label is required to connect to this client group.
description
String description
Contains the client group's description.
is_system_defined
Boolean is_system_defined
If true, this client group is system-defined.
life_cycle
int life_cycle
Represents the client group's life cycle as one of the BrokerAdminClient life cycle values.
name
String name
Contains the client group's name.
required_encryption
int required_encryption
318 webMethods Broker Administration Java API Programmer’s Guide Version 8.2
12 Java API Administration Reference
Contains the client group's required encryption level as one of the BrokerConnectionDescriptor.ENCRYPT_LEVEL_* values, described in the webMethods Broker Client Java API Programmer’s Guide.
storage_type
int storage_type
Represents the client group's queue storage type using one of the BrokerTypeDef storage values, described in the table in BrokerAdminTypeDef.
Constructors
BrokerClientGroupInfo
BrokerClientGroupInfo()
Creates an empty client group information object.
BrokerClientGroupInfo
BrokerClientGroupInfo( String new_name, String new_description, int new_life_cycle, int new_storage_type)
Creates a BrokerClientGroupInfo object, initialized with the specified name, description, life-cycle, and event queue storage type.
Note: For information on client group name restrictions, see the webMethods Broker Client Java API Programmer’s Guide.
new_name The name for the client group.
new_description The client group's description.
new_life_cycle The life cycle of Broker clients that belong to this group. This must be one of these BrokerAdminClient lifecycle values as described in “Constants” on page 180.
new_storage_type The storage type of the event queue for clients associated with the group. Must be one of BrokerTypeDef storage values as described in the table in BrokerAdminTypeDef.
webMethods Broker Administration Java API Programmer’s Guide Version 8.2 319
12 Java API Administration Reference
Methods
toString
String toString()
Returns a human-readable string that contains the client group information.
toString
String toString( int indent_level)
Returns a human-readable string that contains the client group information.
BrokerClientInfo
class BrokerClientInfo extends java.lang.Object
This class represents the information maintained by a Broker for each Broker client that is created for that Broker.
Variables
access_label
String access_label
Contains the access label of the entity using this Broker client.
app_name
String app_name
Contains the Broker client's application name.
authenticator_name
String app_name
Contains the name of the authenticating entity for the Broker client's access label.
can_share_state
boolean can_share_state
indent_level The number of 4-space indentations that should be generated in the output.
320 webMethods Broker Administration Java API Programmer’s Guide Version 8.2
12 Java API Administration Reference
If set to true, the Broker client can share its state, including its event queue. The maximum number of sharing clients is defined by the variable state_share_limit. If set to false, no other Broker client may use this client's identifier or share its state.
client_group
String client_group
Contains the name of the client group to which the Broker client belongs.
client_id
String client_id
Contains the Broker client's identifier.
high_pub_seqn
int high_pub_seqn
The highest publish sequence number that has been used by the client.
sessions
BrokerClientSession sessions[]
An array of BrokerClientSession objects describes the Broker client's currently connected sessions.
shared_event_ordering
String shared_event_ordering
The event ordering mode that will be applied to shared state clients. Valid values are BrokerConnectionDescriptor.SHARED_ORDER_*, described in the webMethods Broker Client Java API Programmer’s Guide.
state_share_limit
int state_share_limit
Defines the maximum number of Broker clients that may share state with this Broker client. If set to -1, there is no limit. This variable will be set to 1 if can_share_state is false. Otherwise this variable should contain a positive number.
user_name
String user_name
Contains the name of the owner using the Broker client.
webMethods Broker Administration Java API Programmer’s Guide Version 8.2 321
12 Java API Administration Reference
Constructors
BrokerClientInfo
BrokerClientInfo()
Creates an empty client information object.
BrokerClientInfo
BrokerClientInfo( String new_client_id, String new_client_group, String new_app_name, boolean new_can_share_state, int new_state_share_limit, long new_high_pub_seqn)
Creates a BrokerClientInfo object, initialized with the specified client id, client group, application name, state sharing indicator, and state sharing limit.
Methods
toCompleteString
String toCompleteString()
Returns a human-readable string containing the client information, including all session information.
toString
String toString()
new_client_id The Broker client's identifier.
new_client_group The client group with which the Broker client is associated.
new_app_name The Broker client's application name.
new_can_share_state If true, this indicates the Broker client can share its state, including its event queue, with the number of Broker clients defined in new_state_share_limit. If false, other Broker clients may not use this client's identifier or share its state.
new_state_share_limit The number of Broker clients that may share this client's state. You can set a value of -1 to indicate there is no limit. Otherwise this parameter should contain a positive value.
new_high_pub_seqn The highest publish sequence number for this client. Should be set to zero or a positive number.
322 webMethods Broker Administration Java API Programmer’s Guide Version 8.2
12 Java API Administration Reference
Returns a human-readable string containing the client information. The string does not contain any session information.
toString
String toString( int indent_level)
Returns a human-readable string containing the client information. The string does not contain any session information.
BrokerClientQueueBrowser
See Also:
BrokerQueueBrowser
class BrokerClientQueueBrowser extends java.lang.Object
This class provides basic queue browsing capabilities to examine the contents of a client queue.
Methods
browseEvents
BrokerEvent[] browseEvents( int max_events, int msecs) throws BrokerException
Browses the client queue and returns one or more events from the client queue. Returns immediately with one of the following:
An array of events if found. The number of events being returned is not guaranteed to be max_events even if there are more than max_events in the client's queue. Any number of events up to the value of max_events may be returned.
An error if the end of queue is reached. 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.
In addition to the listed exceptions, any communications exception can be thrown.
indent_level The number of 4-space indentations that should be generated in the output.
webMethods Broker Administration Java API Programmer’s Guide Version 8.2 323
12 Java API Administration Reference
closeQueueBrowser
BrokerClientQueueBrowserInfo getBrowserInfo() throws BrokerException
Gets information on the current queue browser. Returns a BrokerClientQueueBrowser object.
getBrowserInfo
BrokerClientQueueBrowserInfo getBrowserInfo() throws BrokerException
Gets information on the current queue browser. Returns a BrokerClientQueueBrowser object.
getFilters
void getFilters() throws BrokerException
Returns the filters set on the queue browser.
Possible Exceptions Meaning
BrokerTimeoutException The timeout is reached before any events arrive.
BrokerOutOfRangeException The max_events or msecs parameter is less than zero.
BrokerClientQueueBrowserException The queue browser is invalid.
BrokerClientQueueBrowserException The event at the last cursor position was removed. Reset the cursor to a valid position before attempting a browse operation.
BrokerClientQueueBrowserException The client queue is busy; retry the operation later.
Possible Exceptions Meaning
BrokerClientQueueBrowserException The queue browser is invalid.
Possible Exceptions Meaning
BrokerClientQueueBrowserException The queue browser is invalid.
Possible Exceptions Meaning
BrokerClientQueueBrowserException The queue browser is invalid.
324 webMethods Broker Administration Java API Programmer’s Guide Version 8.2
12 Java API Administration Reference
resetFilters
void resetFilters() throws BrokerException
Removes the filters set on the queue browser. Any subsequent browse requests would consider all the events in the queue.
setFilter
void setFilter( BrokerFilterDescriptor filter) throws BrokerException
Sets the filter for queue browser's browse operation. Any subsequent browse requests would return only those events that satisfy the filter condition. If a filter for the specified document type already exists on the queue browser, it will be overwritten with the new filter setting.
setFilters
void setFilters( BrokerFilterDescriptor filters) throws BrokerException
Sets filters for queue browser's browse operation. Any subsequent browse requests would return only those events that satisfy the filter condition. If a filter for the specified document type already exists on the queue browser, it will be overwritten with the new filter setting.
Possible Exceptions Meaning
BrokerClientQueueBrowserException The queue browser is invalid.
Possible Exceptions Meaning
BrokerClientQueueBrowserException The queue browser is invalid.
BrokerFilterParseException An error occurred while parsing the filter expression
BrokerInvalidFilterException The specified filter expression on the filter object is invalid.
BrokerNullParameterException The filter parameter is null or the filter expression on the BrokerFilterDescriptor is null.
BrokerUnknownEventTypeException The specified event type on the filter object does not exist on the Broker.
Possible Exceptions Meaning
BrokerClientQueueBrowserException The queue browser is invalid.
webMethods Broker Administration Java API Programmer’s Guide Version 8.2 325
12 Java API Administration Reference
setPosition
void setPosition( int position) throws BrokerException
Set the browser's cursor position to the specified position on the queue, where a value of '0' represents the head of the queue and a value of "queue length minus one" represents the end of the queue. Valid position values are in the range of 0 and "queue length-1".
BrokerClientQueueBrowserInfo
See Also:
BrokerQueueBrowser
class BrokerClientQueueBrowserInfo extends java.lang.Object
This class holds detailed information of a client queue browser.
Variables
clientId
String clientId
Client ID of the queue that is being browsed.
browserId
String browserId
BrokerFilterParseException An error occurred while parsing the filter expression
BrokerInvalidFilterException The specified filter expression on the filter object is invalid.
BrokerNullParameterException The filters parameter is null or the filter expression on the BrokerFilterDescriptor is null.
BrokerUnknownEventTypeException The specified event type on the filter object does not exist on the Broker.
Possible Exceptions Meaning
BrokerClientQueueBrowserException The queue browser is invalid or the specified queue position is out of bounds: the position is less than zero or the position is greater than/equal to the queue length.
Possible Exceptions Meaning
326 webMethods Broker Administration Java API Programmer’s Guide Version 8.2
12 Java API Administration Reference
Client ID of the client that is browsing the queue.
browserSessionId
int browserSessionId
Session ID of the browsing client.
locked
boolean locked
Queue locked flag
createTime
long createTime
Queue browser creation time. For BrokerLockedClientQueueBrowsers, this would be the lock acquisition time.
Constructors
BrokerClientQueueBrowserInfo
BrokerClientQueueBrowserInfo ()
Create an empty browser info object.
BrokerClientQueueBrowserInfo
BrokerClientQueueBrowserInfo( String clientId, String browserId, int browserSessionId, boolean locked, boolean acquired, int createTime)
Create and initialize a browser info object.
BrokerClientSession
class BrokerClientSession extends java.lang.Object
This class represents information stored by a Broker for each client application that is currently connected to that Broker. A Broker client may share its client state, which means several client applications may create BrokerClient objects using the same client identifier. Each of these client application connections is described by a BrokerClientSession object.
webMethods Broker Administration Java API Programmer’s Guide Version 8.2 327
12 Java API Administration Reference
Variables
auth_info
BrokerAuthInfo auth_info
The authentication information for the session. See also BrokerAuthInfo on page 315.
auth_protocol
String auth_protocol
The authorization protocol for this session.
auth_version
String auth_verison
If auth_protocol is set, the authentication protocol version for the session.
connect_time
BrokerDate connect_time
Contains the time that the Broker client connected to the Broker. This may differ from the create_time if the connection is shared with other clients in the application.
connection_id
int connection_id
Contains the Broker client's connection identifier.
create_time
BrokerDate create_time
Contains the date and time the Broker client's session was created.
encrypt_level
String encrypt_level
The encryption level for the session, if encrypt_protocol is set.
encrypt_protocol
String encrypt_protocol
The encryption protocol to use for the session, defined as one of the BrokerConnectionDescriptor.ENCRYPT_LEVEL_* values described in the webMethods Broker Client Java API Programmer’s Guide.
328 webMethods Broker Administration Java API Programmer’s Guide Version 8.2
12 Java API Administration Reference
encrypt_version
String encrypt_version
The encryption protocol for the session, if encrypt_protocol is set.
ip_address
int ip_address
Contains the IP address of the Broker client's host.
last_activity_time
BrokerDate last_activity_time
Contains the last time that data was sent over the Broker client's connection with the Broker.
platform_info
Hashtable platform_info
Contains the Broker client's platform information, which describes the operating system and version, the hardware platform, and the version of the webMethods Broker API the client is using. See the webMethods Broker Client Java API Programmer’s Guide for a complete discussion of platform information.
port
int port
Contains the port number used by Broker client.
session_id
int session_id
Contains the Broker client's session identifier.
ssl_certificate
BrokerSSLCertificate ssl_distinguished_name
Contains the SSL certificate, if encrypt_protocol is SSL.
Constructors
BrokerClientSession
BrokerClientSession()
webMethods Broker Administration Java API Programmer’s Guide Version 8.2 329
12 Java API Administration Reference
Creates an empty client session object.
BrokerClientSession
BrokerClientSession( int new_session_id, int new_connection_id, int new_ip_address, int new_port, boolean new_encrypt_protocol, boolean new_encrypt_version, String new_auth_protocol, String new_auth_version, BrokerSSLCertificate new_ssl_certificate, BrokerDate new_connect_time, BrokerDate new_create_time, BrokerDate new_last_activity_time)
Creates a BrokerClientSession object, initialized with the specified parameters.
Methods
toString
String toString()
Returns a human-readable string containing the client session information.
new_session_id The Broker client's identifier.
new_connection_id The Broker client connection identifier.
new_ip_address The Broker client's IP address.
new_port The port number for the session.
new_encrypt_protocol The encryption protocol for the session.
new_encrypt_version The encryption version for the session.
new_encyrpt_level The level of encryption for the session.
new_auth_protocol The authentication protocol for the session.
new_auth_version The authentication version for the session.
BrokerSSLCentificate The SSL certificate for the session.
new_connect_time The time the client connected to the Broker.
new_create_time The time the client session was created.
new_last_activity_time The time data was last sent across the connection between the client and the Broker.
330 webMethods Broker Administration Java API Programmer’s Guide Version 8.2
12 Java API Administration Reference
BrokerClusterGatewayInfo
class BrokerClusterGatewayInfo extends java.lang.Object
This class is used to store configuration about a cluster gateway. A gateway connects two distinct clusters so that Broker clients in one cluster can subscribe to and publish events to clients in the other cluster. The gateway consists of two Brokers, each representing a distinct cluster.
See Chapter 8, “Managing Broker Clusters” for more information on clusters.
Variables
accessible_clusters
String accessible_clusters[]
The list of clusters that are accessible through this gateway.
auth_type
int auth_type
The type of authentication used by the gateway. For information about the BrokerAdminClient.AUTH_TYPE_* values for this variable, see “Constants” on page 180.
encrypt_level
int encrpyt_level
The level of encryption required by the gateway. Valid values are BrokerConnectionDescriptor.ENCRYPT_LEVEL_* values are described in the webMethods Broker Client Java API Programmer’s Guide.
gateway_broker_name
String gateway_broker_name
The name of the Broker that is the gateway for this cluster.
gateway_host_name
String gateway_host_name
The host on which the gateway Broker is running.
is_complete
boolean is_complete
webMethods Broker Administration Java API Programmer’s Guide Version 8.2 331
12 Java API Administration Reference
If true, the BrokerAdminClient.createClusterGateway method has been invoked on each of the two Broker that make up the gateway. If false, only one Broker has invoked the createClusterGateway method and the gateway is not yet complete.
is_local
boolean is_local
If true, the gateway is on the current Broker. If false, the gateway is on another Broker.
is_primary_gateway
boolean is_primary_gateway
If true, the primary cluster gateway is on the current Broker. If false, the primary cluster gateway is on another Broker.
remote_broker_description
String remote_broker_description
The description of the remote Broker that is acting as the other end of the gateway.
remote_broker_name
String remote_broker_name
The name of the remote Broker that is acting as the other end of the gateway.
remote_cluster_name
String remote_cluster_name
The name of the cluster that the remote Broker is presenting to the gateway.
remote_host_name
String remote_host_name
The host name that is running the remote Broker.
Methods
toString
String toString()
Returns a string containing the cluster gateway information.
332 webMethods Broker Administration Java API Programmer’s Guide Version 8.2
12 Java API Administration Reference
toString
String toString( int indent_level, boolean hide_gateway_broker, boolean hide_accessible_clusters)
Returns a string containing the cluster gateway information.
BrokerClusterInfo
class BrokerClusterInfo extends java.lang.Object
This class is used to store configuration about a group of Brokers that make up a cluster.
See Chapter 8, “Managing Broker Clusters” for more information on clusters.
Variables
auth_type
int auth_type
The type of authentication used by the cluster. For information about the BrokerAdminClient.AUTH_TYPE_* values for this variable, see “Constants” on page 180.
cluster_name
String cluster_name
The name of the cluster.
encrypt_level
int encrpyt_level
The level of encryption required by the gateway. Valid values are BrokerConnectionDescriptor.ENCRYPT_LEVEL_* values are described in the webMethods Broker Client Java API Programmer’s Guide.
isLocalPublish
boolean isLocalPublish
indent_level The number of 4-character spaces to use for indentation.
hide_gateway_broker If set to true, the gateway Broker's host and name as well as the is_local information, will be omitted.
hide_accessible_clusters If set to true, the accessible_clusters and is_complete information will be omitted.
webMethods Broker Administration Java API Programmer’s Guide Version 8.2 333
12 Java API Administration Reference
Specifies whether document forwarding is enabled or disabled in the cluster.
Constructor
BrokerClusterInfo
BrokerClusterInfo()
Creates an empty cluster information object.
BrokerClusterInfo
BrokerClusterInfo( BrokerTerritoryInfo terrInfo)
Creates a cluster information object from a territory information object.
Methods
toString
String toString()
Returns a string containing the cluster information.
toString
String toString( int indent_level)
Returns a string containing the cluster information.
BrokerCompleteBroker
class BrokerCompleteBroker extends java.lang.Object
This class represents all configuration information about a Broker and is used to load, save, import or export the Broker's configuration.
Variables
broker_name
String broker_name
Contains the Broker Server's name.
indent_level The number of 4-character spaces to use for indentation.
334 webMethods Broker Administration Java API Programmer’s Guide Version 8.2
12 Java API Administration Reference
brokers_in_territory
BrokerInfo brokers_in_territory[]
Contains an array of BrokerInfo objects that describes all the Brokers in this Broker's territory.
client_groups
BrokerCompleteClientGroup client_groups[]
Contains an array of BrokerCompleteClientGroup objects that describes all the client groups defined in this Broker.
clients
BrokerCompleteClient[]
Contains an array of BrokerCompleteClient objects that describes all the of this Broker's clients.
description
String broker_name
Contains the Broker's description.
event_types
BrokerCompleteEventType event_types[]
Contains an array of BrokerCompleteEventType objects that describes all the event types defined in this Broker.
is_default
boolean is_default
Set to true if this is the default Broker.
territory_name
String territory_name
Contains the Broker's territory.
Constructors
BrokerCompleteBroker
BrokerCompleteBroker()
Creates an empty BrokerCompleteBroker object.
webMethods Broker Administration Java API Programmer’s Guide Version 8.2 335
12 Java API Administration Reference
BrokerCompleteBroker
BrokerCompleteBroker( BrokerInfo info)
Creates a BrokerCompleteBroker object and initializes it from a BrokerInfo object.
Methods
deepRefresh
void deepRefresh( BrokerAdminClient client) throws BrokerException
Refreshes this object's Broker information, based on the specified administrative Broker client. The client_groups and event_types data members will be updated using the BrokerCompleteClientGroup.retrieve and BrokerCompleteEventType.retrieve methods.
Any client groups or event types which no longer exist, or which this client does not have permission to read, will be removed from this object.
Note: The is_default data member will be updated if, and only if, this object was created using the BrokerCompleteServer.deepRefresh method.
See Also:
BrokerCompleteBroker.refresh
deepRetrieve
static BrokerCompleteBroker deepRetrieve( BrokerAdminClient client) throws BrokerException
info The BrokerInfo object used to initialize this object.
client The administrative client to be used to refresh this object.
Possible Exceptions Meaning
BrokerInvalidClientException The BrokerAdminClient has been destroyed or disconnected.
BrokerNullParameterException The client parameter is null.
client The administrative client to be used to retrieve the Broker information.
336 webMethods Broker Administration Java API Programmer’s Guide Version 8.2
12 Java API Administration Reference
Returns a BrokerCompleteBroker object containing information on the Broker to which the administrative Broker client is connected. All client groups and event types which this client has permission to access will be set in the data members client_groups and event_types data members, using the BrokerCompleteClientGroup.retrieve and BrokerCompleteEventType.retrieve methods.
Note: The is_default data member will be set if, and only if, this object was created using the BrokerCompleteServer.deepRefresh method.
See Also:
BrokerCompleteBroker.retrieve
deepStore
void deepStore( BrokerAdminClient client) throws BrokerException
Stores the information from this object into the Broker to which the client is connected.
The broker_name, brokers_in_territory, is_default, and territory_name data members are ignored. If the description has been set, it replaces the Broker's existing description.
The information contained in the client_groups and event_types data members are stored using the BrokerCompleteClientGroup.store and BrokerCompleteEventType.store methods.
If an exception is thrown, none of the Broker's information will be modified.
Possible Exceptions Meaning
BrokerInvalidClientException The BrokerAdminClient has been destroyed or disconnected.
BrokerNullParameterException The client parameter is null.
client The administrative client to be used to store the Broker information.
Possible Exceptions Meaning
BrokerInvalidClientException The BrokerAdminClient has been destroyed or disconnected.
BrokerInvalidClientGroupNameException Specified client group name is not valid.
BrokerNoPermissionException The client does not have permission to change the Broker's configuration.
BrokerNullParameterException The client parameter is null.
BrokerOutOfRangeException A client group contained an invalid value for its life cycle or storage parameter type.
webMethods Broker Administration Java API Programmer’s Guide Version 8.2 337
12 Java API Administration Reference
See Also:
BrokerCompleteBroker.store
refresh
void refresh( BrokerAdminClient client) throws BrokerException
Refreshes this object's Broker information, based on the specified administrative Broker client. The client_groups and event_types data members are not updated.
Note: The is_default data member will be updated if, and only if, this object was created using the BrokerCompleteServer.deepRefresh method.
See Also:
BrokerCompleteBroker.deepRefresh
retrieve
static BrokerCompleteBroker retrieve( BrokerAdminClient client) throws BrokerException
Returns a BrokerCompleteBroker object containing information on the Broker to which the administrative Broker client is connected.
The default Broker status will be set only if this BrokerCompleteBroker object was created by a BrokerCompleteServer or BrokerCompleteCollection method.
No client group or event type information is retrieved.
BrokerUnknownEventTypeException A client group contains an event type in its can_publish or can_subscribe list that does not exist on the Broker.
client The administrative client to be used to refresh this object.
Possible Exceptions Meaning
BrokerInvalidClientException The BrokerAdminClient has been destroyed or disconnected.
BrokerNullParameterException The client parameter is null.
client The administrative client to be used to retrieve contents for this object.
Possible Exceptions Meaning
338 webMethods Broker Administration Java API Programmer’s Guide Version 8.2
12 Java API Administration Reference
See Also:
BrokerCompleteBroker.deepRetrieve
store
void deepStore( BrokerAdminClient client) throws BrokerException
Stores most of the information from this object into the Broker to which the client is connected. The broker_name, brokers_in_territory, is_default, and territory_name are not stored into the Broker.
If an exception is thrown, none of the Broker's information will be modified.
See Also:
BrokerCompleteBroker.deepStore
toString
String toString()
Converts the information contained in this object into a string in ADL format that may be saved to a file. For more information on ADL, see Administering webMethods Broker.
Returns an empty string if all of the data members are null or if their conversion results in an empty string.
Possible Exceptions Meaning
BrokerInvalidClientException The BrokerAdminClient has been destroyed or disconnected.
BrokerNullParameterException The client parameter is null.
client The administrative client to be used to store the Broker information.
Possible Exceptions Meaning
BrokerInvalidClientException The BrokerAdminClient has been destroyed or disconnected.
BrokerNoPermissionException The client does not have permission to change the Broker's configuration.
BrokerNullParameterException The client parameter is null.
webMethods Broker Administration Java API Programmer’s Guide Version 8.2 339
12 Java API Administration Reference
toString
String toString( int indent_level) throws BrokerException
Converts the information contained in this object into a string in ADL format that may be saved to a file. For more information on ADL, see Administering webMethods Broker.
Returns an empty string if all of the data members are null or if their conversion results in an empty string.
write
void write( Writer writer, int indent_level) throws BrokerException, IOException
Writes out this object's Broker information in ADL format, usually to a file. No data will be written if the broker_name is null.
For more information on ADL, see Administering webMethods Broker.
BrokerCompleteClient
class BrokerCompleteClient extends java.lang.Object
This class represents all configuration information about a Broker client and is used to load, save, import or export the client's configuration.
indent_level The number of 4-character spaces to use for indentation.
Possible Exceptions Meaning
BrokerOutOfRangeException The indent_level parameter is less than 0.
writer The file where the data is to be written.
indent_level The number of 4-character spaces to use for indentation.
Possible Exceptions Meaning
IOException There was an error writing the data to the file.
BrokerNullParameterException The writer parameter is null.
BrokerOutOfRangeException The indent_level parameter is less than 0.
340 webMethods Broker Administration Java API Programmer’s Guide Version 8.2
12 Java API Administration Reference
Variables
client_info
BrokerClientInfo client_info
Contains the Broker client's information. See BrokerClientInfo for more information.
infoset
BrokerEvent infoset
Contains the Broker client's infoset. See the webMethods Broker Client Java API Programmer’s Guide for more information on client infosets.
replace_subscriptions_on_store
boolean replace_subscriptions_on_store
If set to true, all of the Broker client's event subscriptions will be replaced when the store method is invoked.
subscriptions
BrokerSubscription subscriptions[]
Contains the Broker client's list of event subscriptions.
Constructors
BrokerCompleteClient
BrokerCompleteClient()
Creates an empty BrokerCompleteClient object.
BrokerCompleteClient
BrokerCompleteClient( BrokerClientInfo info)
This is a copy constructor.
info The object being copied.
webMethods Broker Administration Java API Programmer’s Guide Version 8.2 341
12 Java API Administration Reference
Methods
refresh
void refresh( BrokerAdminClient client) throws BrokerException
Refreshes this object's Broker information, based on the specified administrative Broker client. The client_info.client_id variable must be set to the client id for client.
See Also:
BrokerCompleteClient.retrieve
retrieve
static BrokerCompleteBroker retrieve( BrokerAdminClient client) throws BrokerException
Returns a BrokerCompleteClient object containing information on the specified client.
client The administrative client to be used to refresh this object.
Possible Exceptions Meaning
BrokerInvalidClientException The BrokerAdminClient has been destroyed or disconnected.
BrokerNullParameterException The client parameter is null.
BrokerNoPermissionException The client does not have permission to browse the information.
BrokerUnknownClientIdException The client ID specified in the client_info.client_id variable does not exist on the Broker.
client The administrative client to be used to retrieve contents for this object.
Possible Exceptions Meaning
BrokerInvalidClientException The BrokerAdminClient has been destroyed or disconnected.
BrokerNullParameterException The client parameter is null.
BrokerNoPermissionException The client does not have permission to browse the information.
342 webMethods Broker Administration Java API Programmer’s Guide Version 8.2
12 Java API Administration Reference
See Also:
BrokerCompleteClient.refresh
store
void deepStore( BrokerAdminClient client) throws BrokerException
Stores most of the information from this object for the Broker client. If the client is not a member of a Client Group with an explicit-destroy life cycle, calling this method will have no effect.
If the Broker client does not exist on the Broker, it will be created and initialized with the information is set in this object.
If the Broker client does exist, then some information is overwritten and some information merged with the existing settings as follows:
The app_name, client_group, high_pub_seqn, can_share_state, user_name and authenticator_name fields in the client_info object are ignored if the client already exists. These values are only set when creating the Broker client.
The access_label field in the client_info object is always ignored.
If the state_share_limit in the client_info object is non-zero and the can_share_state flag is true in an existing or new client, the state_share_limit will be set with the new value.
If the subscriptions list is set, its content will be merged with any existing subscriptions. If the replace_subscriptions_on_store flag is true, this list of subscriptions will replace the previous list.
If the infoset is set, it replaces the existing client infoset.
If an exception is thrown, none of the Broker client's information will be modified.
BrokerUnknownClientIdException The client id specified in the client_info.client_id variable does not exist on the Broker.
client The administrative client to be used to store the Broker information.
Possible Exceptions Meaning
BrokerInvalidClientException The BrokerAdminClient has been destroyed or disconnected.
BrokerInvalidSubscriptionException The filter string in a subscription in the subscriptions variable contains a parse error.
Possible Exceptions Meaning
webMethods Broker Administration Java API Programmer’s Guide Version 8.2 343
12 Java API Administration Reference
See Also:
BrokerCompleteClient.retrieve
toString
String toString()
Converts the information contained in this object into a string in ADL format that may be saved to a file. For more information on ADL, see Administering webMethods Broker.
Returns an empty string if all of the data members are null or if their conversion results in an empty string.
See:
BrokerCompleteClient.write
toString
String toString( int indent_level) throws BrokerException
Converts the information contained in this object into a string in ADL format that may be saved to a file. For more information on ADL, see Administering webMethods Broker.
Returns an empty string if all of the data members are null or if their conversion results in an empty string.
BrokerNoPermissionException The client does not have permission to change the Broker's configuration.
BrokerNullParameterException The client parameter is null.
BrokerOutOfRangeException A sub_id element in a subscription contained in subscriptions is less than zero or the state_share_limit element is less than -1.
BrokerUnknownClientGroupException The client group in the client_info.client_group variable does not exist on the Broker.
BrokerUnknownEventTypeException The event type name listed in one of the subscriptions does not exist on the Broker. All other subscriptions are still created if this exception is thrown.
indent_level The number of 4-character spaces to use for indentation.
Possible Exceptions Meaning
344 webMethods Broker Administration Java API Programmer’s Guide Version 8.2
12 Java API Administration Reference
See Also:
BrokerCompleteClient.write.
write
void write( Writer writer, int indent_level) throws BrokerException, IOException
Writes out this object's Broker information in ADL format, usually to a file. No data will be written if the client_info is null.
For more information on ADL, see Administering webMethods Broker.
See Also:
BrokerCompleteClient.toString.
BrokerCompleteClientGroupclass BrokerCompleteClientGroup extends java.lang.Object
This class represents all configuration information about a client group and is used to load, save, import or export the group's configuration.
Variables
acl
BrokerAccessControlList acl
Contains the distinguished names of entities which may create clients in this group. See BrokerServerClient for details.
Possible Exceptions Meaning
BrokerOutOfRangeException The indent_level parameter is less than 0.
writer The file where the data is to be written.
indent_level The number of 4-character spaces to use for indentation.
Possible Exceptions Meaning
IOException There was an error writing the data to the file.
BrokerNullParameterException The writer parameter is null.
BrokerOutOfRangeException The indent_level parameter is less than 0.
webMethods Broker Administration Java API Programmer’s Guide Version 8.2 345
12 Java API Administration Reference
can_publish
String can_publish[]
Contains an array of event type names which can be published by clients in this group.
can_subscribe
String can_subscribe[]
Contains an array of event type names to which client's in this group can subscribe.
client_group_info
BrokerClientGroupInfo client_group_info
Contains information about this client group. See BrokerClientGroupInfo for details.
ignore_change_errors_on_store
boolean ignore_change_errors_on_store
If set to true, this flag disables any permission exceptions that otherwise might occur when you try use the store method.
replace_lists_on_store
boolean replace_lists_on_store
If set to true, any event types that exist in the Broker's can-publish and can-subscribe lists for this client group, but which are not specified by this object will be deleted when this object's store method is invoked. If replace_infosets_on_store is false, pre-existing event types on the Broker will not be deleted when the store method is invoked.
Constructors
BrokerCompleteClientGroup
BrokerCompleteClientGroup()
Creates an empty BrokerCompleteClientGroup object.
BrokerCompleteClientGroup
BrokerCompleteClientGroup( BrokerClientGroupInfo info)
Creates a BrokerCompleteBroker object and initializes it from a BrokerClientGroupInfo object.
info The BrokerInfo object used to initialize this object.
346 webMethods Broker Administration Java API Programmer’s Guide Version 8.2
12 Java API Administration Reference
Methods
refresh
void refresh( BrokerAdminClient client) throws BrokerException
Refreshes this object's client group information, using the specified administrative Broker client. The client_group_info.name data member must be set to the name of the desired client group name.
If the access control list cannot be accessed, the acl member will be set to null.
See Also:
BrokerCompleteClientGroup.retrieve
retrieve
static BrokerCompleteClientGroup retrieve( BrokerAdminClient client, String client_group_name) throws BrokerException
Retrieves the information about a specified client group, using the specified administrative client.
client The administrative client to be used to refresh this object.
Possible Exceptions Meaning
BrokerInvalidClientException The BrokerAdminClient has been destroyed or disconnected.
BrokerInvalidClientGroupNameException The specified client group name is not valid.
BrokerNoPermissionException The client does not have permission to read the client group configuration.
BrokerNullParameterException The client parameter, the data member client_group_info, or the variable client_group_info.name is null.
BrokerUnknownClientGroupException The client group does not exist on the Broker.
client The administrative client to be used to retrieve contents for this object.
client_group_name The name of the client group whose information is to be returned.
webMethods Broker Administration Java API Programmer’s Guide Version 8.2 347
12 Java API Administration Reference
If the access control list cannot be accessed, the acl member will be set to null.
See Also:
BrokerCompleteClientGroup.refresh
store
void store( BrokerAdminClient client) throws BrokerException
Store this object's client group information into the Broker to which the specified administrative Broker client is connected.
If the client group does not exist, it is created and initialized from this object.
If the client group already exists, the following rules apply:
If the description data member is set in this object, it will replace the existing client group description on the Broker.
If the can_publish and can_subscribe lists are set, their contents are merged with those for the client group on the Broker.
If the acl data member is set, it replaces the existing one for the client group on the Broker.
The life cycle and storage type properties are not changed for the client group on the Broker.
If the access control list cannot be accessed, the acl member will be set to null.
Possible Exceptions Meaning
BrokerInvalidClientException The BrokerAdminClient has been destroyed or disconnected.
BrokerNoPermissionException The client does not have permission to read the client group configuration.
BrokerNullParameterException The client or client_group_name parameter is null.
BrokerUnknownClientGroupException The client_group_name does not exist on the Broker.
client The administrative client to be used to store this object.
Possible Exceptions Meaning
BrokerInvalidClientException The BrokerAdminClient has been destroyed or disconnected.
348 webMethods Broker Administration Java API Programmer’s Guide Version 8.2
12 Java API Administration Reference
See Also:
BrokerCompleteClientGroup.refreshand BrokerCompleteClientGroup.retrieve
toString
String toString()
Converts the information contained in this object into a string in ADL format that may be saved to a file. For more information on ADL, see Administering webMethods Broker.
Returns an empty string if all of the data members are null or if their conversion results in an empty string.
toString
String toString( int indent_level) throws BrokerException
Converts the information contained in this object into a string in ADL format that can be saved to a file. For more information on ADL, see Administering webMethods Broker.
write
void write( Writer writer, int indent_level) throws BrokerException, IOException
BrokerInvalidClientGroupNameException The specified client group name is not valid.
BrokerNoPermissionException The client does not have permission to read the client group configuration.
BrokerNullParameterException The client parameter, the data member client_group_info, or the variable client_group_info.name is null.l
BrokerUnknownClientGroupException The client group does not exist on the Broker.
indent_level The number of 4-character spaces to use for indentation.
writer The file where the data is to be written.
indent_level The number of 4-character spaces to use for indentation.
Possible Exceptions Meaning
webMethods Broker Administration Java API Programmer’s Guide Version 8.2 349
12 Java API Administration Reference
Writes out this object's Broker information in ADL format, usually to a file. No data will be written if the client_group_info member is null. For more information on ADL, see Administering webMethods Broker.
BrokerCompleteCollectionclass BrokerCompleteCollection extends java.lang.Object
This class is used as a container to collect various Broker objects. It is commonly used to create an export file containing a Broker Server's configuration or to hold the results of an imported configuration file.
Note that several of the objects in this collection are also container objects. Including an object in one of those collection objects can result in that object being placed in an export file or used during an import operation.
Variables
acls
BrokerAccessControlList acls[]
Contains all of the access control lists for this collection.
brokers
BrokerCompleteBroker brokers[]
Contains all the Broker Servers in this collection.
client_groups
BrokerCompleteClientGroup client_groups[]
Contains all of the client groups in this collection.
clients
BrokerCompleteClient clients[]
Contains all of the client groups in this collection.
Possible Exceptions Meaning
IOException There was an error writing the data to the file.
BrokerNullParameterException The writer parameter is null.
BrokerOutOfRangeException The indent_level parameter is less than 0.
350 webMethods Broker Administration Java API Programmer’s Guide Version 8.2
12 Java API Administration Reference
event_types
BrokerCompleteEventType event_types[]
Contains all of the event type definitions for this collection.
servers
BrokerCompleteServer servers[]
Contains all the server definitions in this configuration.
Constructors
BrokerCompleteCollection
BrokerCompleteCollection()
Creates an empty BrokerCompleteCollection object.
Methods
read
static BrokerCompleteCollection read( Reader reader) throws BrokerException, IOException
Creates a new BrokerCompleteCollection object from the text supplied from reader. The input is usually read from a file. The reader can only be read from once. Unlike the readFile method, this method does not support the file formats used in earlier releases of webMethods Broker.
For greater efficiency, do not pass a BufferedReader because the underlying parser already performs read buffering.
See Also:
BrokerCompleteCollection.readFile
reader The file from which the configuration is to be created.
Possible Exceptions Meaning
IOException There was an error reading data from the file.
BrokerInputParseException There was a parse error in the input data.
BrokerNullParameterException The reader parameter is null.
webMethods Broker Administration Java API Programmer’s Guide Version 8.2 351
12 Java API Administration Reference
readFile
static BrokerCompleteCollection readFile( String filename) throws BrokerException, IOException
Creates a new BrokerCompleteCollection object from the text supplied from the file with the specified filename.
If the file does not use the most current file format, an attempt will be made to re-read the file using a file format from previous webMethods Broker release.
See Also:
BrokerCompleteCollection.readFile
toString
String toString()
Converts the information contained in this object into a string in ADL format that may be saved to a file. For more information on ADL, see Administering webMethods Broker.
Returns an empty string if all of the data members are null or if their conversion results in an empty string.
toString
String toString( int indent_level) throws BrokerException
Converts the information contained in this object into a string in ADL format that may be saved to a file. For more information on ADL, see Administering webMethods Broker.
Returns an empty string if all of the data members are null or if their conversion results in an empty string.
reader The file from which the configuration is to be created.
Possible Exceptions Meaning
IOException There was an error reading data from the file.
BrokerInputParseException There was a parse error in the input data.
BrokerNullParameterException The filename parameter is null.
indent_level The number of 4-character spaces to use for indentation.
352 webMethods Broker Administration Java API Programmer’s Guide Version 8.2
12 Java API Administration Reference
write
void write( Writer writer, int indent_level) throws BrokerException, IOException
Writes out this object's information in ADL format, usually to a file. No data will be written if all of the data members are null or if all of them return empty strings when converted to strings. For more information on ADL, see Administering webMethods Broker.
Returns an empty string if all of the data members are null or if their conversion results in an empty string.
You can call this method repeatedly with the same Writer to write multiple collections into a single file.
This method does not write the export file format version number to the file. Invoke the writeVersionNumber method once before invoking this method to write the version number to the beginning of the file.
See Also:
BrokerCompleteCollection.writeVersionNumber
writeVersionNumber
static void writeVersionNumber( Writer writer, int indent_level) throws BrokerException, IOException
Writes out this object's version, usually to a file. This method is usually invoked before invoking the write method of this class, or any other BrokerComplete* class, so that the version number appears before the configuration information.The inclusion of the file format version at the top of the exported file is not mandatory.
writer The file where the data is to be written.
indent_level The number of 4-character spaces to use for indentation.
Possible Exceptions Meaning
IOException There was an error writing the data to the file.
BrokerNullParameterException The writer parameter is null.
BrokerOutOfRangeException The indent_level parameter is less than 0.
writer The file where the version number is to be written.
indent_level The number of 4-character spaces to use for indentation.
webMethods Broker Administration Java API Programmer’s Guide Version 8.2 353
12 Java API Administration Reference
The writing of the version number was separated from the BrokerComplete*.write methods so that you may control which parts of a collection are written to the file and write the version number only once, at the top of the file.
See Also:
BrokerCompleteBroker.write, BrokerCompleteClientGroup.write, BrokerCompleteEventType.write, and BrokerCompleteServer.write
BrokerCompleteEventTypeclass BrokerCompleteEventType extends java.lang.Object
This class represents all configuration information for a event type and is used to load, save, import or export a Broker's configuration.
Variables
infosets
BrokerEvent infosets[]
Contains all the infosets for this event type.
replace_infosets_on_store
boolean replace_infosets_on_store
If set to true, any infosets that exist on the Broker but are not specified by this object will be deleted when this object's store method is invoked. If replace_infosets_on_store is false, pre-existing infosets on the Broker will not be deleted when the store method is invoked.
type_def
BrokerAdminTypeDef type_def
Contains the event type definition.
Possible Exceptions Meaning
IOException There was an error writing the data to the file.
BrokerNullParameterException The writer parameter is null.
BrokerOutOfRangeException The indent_level parameter is less than 0.
354 webMethods Broker Administration Java API Programmer’s Guide Version 8.2
12 Java API Administration Reference
Constructors
BrokerCompleteEventType
BrokerCompleteEventType()
Creates an empty BrokerCompleteEventType object.
BrokerCompleteEventType
BrokerCompleteEventType(BrokerAdminTypeDef type_def
Creates a BrokerCompleteEventType object, initialized from the specified administrative type definition object.
Methods
refresh
void refresh( BrokerAdminClient client) throws BrokerException
Refreshes this object's event type information, using the specified administrative Broker client. The data member type_def must be set.
See Also:
BrokerCompleteEventType.retrieve
type_def The BrokerAdminTypeDef used to initialize this object.
client The administrative client to be used to refresh this object.
Possible Exceptions Meaning
BrokerInvalidClientException The BrokerAdminClient has been destroyed or disconnected.
BrokerNoPermissionException The client does not have permission to read the event type configuration.
BrokerNullParameterException The client parameter or the data member type_def is null, or the type_def has a null event type name.
BrokerUnknownEventTypeException The event type contained in the object specified by type_def not exist on the Broker.
webMethods Broker Administration Java API Programmer’s Guide Version 8.2 355
12 Java API Administration Reference
retrieve
static BrokerCompleteEventType retrieve( BrokerAdminClient client, String event_type_name) throws BrokerException
Retrieves the information about a specified event type, using the specified administrative client.
See Also:
BrokerCompleteEventType.refresh
store
void store( BrokerAdminClient client) throws BrokerException
Store this object's event type information into the Broker to which the specified administrative Broker client is connected.
If the event type does not exist, it is created and initialized from this object.
If the event type already exists, the following rules apply:
The type definition, time-to-live, storage type, and description replace the values for the type definition on the Broker.
If any infosets specified do not currently exist on the Broker, they will be added for this event type. If any infosets specified already exist on the Broker, they will be replaced.
client The administrative client to be used to retrieve contents for this object.
event_type_name The name of the client group whose information is to be returned.
Possible Exceptions Meaning
BrokerInvalidClientException The BrokerAdminClient has been destroyed or disconnected.
BrokerNoPermissionException The client does not have permission to read the event type configuration.
BrokerNullParameterException The client or event_type_name parameter is null.
BrokerUnknownEventTypeException The event_type_name does not exist on the Broker.
client The administrative client to be used to store this object.
356 webMethods Broker Administration Java API Programmer’s Guide Version 8.2
12 Java API Administration Reference
If replace_infosets_on_store is true, any infosets that exist on the Broker but are not specified by this object will be deleted. If replace_infosets_on_store is false, pre-existing infosets on the Broker will not be deleted.
If an exception is thrown, the Broker will not have been updated.
See Also:
BrokerCompleteEventType.refresh and BrokerCompleteEventType.retrieve
toString
String toString()
Converts the event type information contained in this object into a string in ADL format that may be saved to a file. For more information on ADL, see Administering webMethods Broker.
toString
String toString( int indent_level) throws BrokerException
Converts the event type information contained in this object into a string in ADL format that may be saved to a file. For more information on ADL, see Administering webMethods Broker.
Possible Exceptions Meaning
BrokerInvalidClientException The BrokerAdminClient has been destroyed or disconnected.
BrokerInvalidClientGroupNameException The specified client group name is not valid.
BrokerNoPermissionException The client does not have permission to read the client group configuration.
BrokerNullParameterException The client parameter, the data member client_group_info, or the variable client_group_info.name is null.l
BrokerUnknownClientGroupException The client group does not exist on the Broker.
indent_level The number of 4-character spaces to use for indentation.
webMethods Broker Administration Java API Programmer’s Guide Version 8.2 357
12 Java API Administration Reference
write
void write( Writer writer, int indent_level) throws BrokerException, IOException
Writes out this object's information in ADL format, usually to a file. No data will be written if the type_def member is null.
For more information on ADL, see Administering webMethods Broker.
BrokerCompleteServer
class BrokerCompleteServer extends java.lang.Object
This class represents all configuration information about a Broker Server and is used to load, save, import or export the Broker Server's configuration.
Variables
acl
BrokerAccessControlList acl
Contains the access control list for this Broker Server.
brokers
BrokerCompleteBroker brokers[]
Contains the Broker Servers' names.
description
String description
Contains the Broker's description.
writer The file where the data is to be written.
indent_level The number of 4-character spaces to use for indentation.
Possible Exceptions Meaning
IOException There was an error writing the data to the file.
BrokerNullParameterException The writer parameter is null.
BrokerOutOfRangeException The indent_level parameter is less than 0.
358 webMethods Broker Administration Java API Programmer’s Guide Version 8.2
12 Java API Administration Reference
host_name
String host_name
Contains the Broker host's host name.
license_key
String license_key
Contains the Broker host's license key.
log_config
BrokerLogConfig log_config
Contains the Broker Server's host name.
port
int port
Contains the Broker host's port number.
ssl_config
BrokerSSLConfig ssl_config
Contains the Broker host's SSL configuration.
Important! This field only works with version 6.5.2 or earlier Broker Servers.
Constructors
BrokerCompleteServer
BrokerCompleteServer()
Creates an empty BrokerHost object.
Methods
deepRefresh
void deepRefresh( BrokerAdminClient client, String client_id, String client_group,
webMethods Broker Administration Java API Programmer’s Guide Version 8.2 359
12 Java API Administration Reference
String app_name, BrokerConnectionDescriptor desc) throws BrokerException
Refreshes this object's Broker Server information, based on the specified administrative Broker client. All of this object's data members will be updated.
Any Brokers which no longer exist, or for which the client does not have permission to read, will be removed from the brokers array. The information for each Broker in the array will be refreshed using the BrokerCompleteBroker.deepRefresh method.
The client_id, client_group, app_name, and desc are all used to establish individual connections to each Broker in the brokers array. Any information that the client does not have permission to read will be set to null. For more information, see BrokerAdminClient.
See Also:
BrokerCompleteServer.refresh
deepRetrieve
static BrokerCompleteServer deepRetrieve( BrokerAdminClient client) String client_id, String client_group, String app_name, BrokerConnectionDescriptor desc) throws BrokerException
client The administrative client to be used to refresh this object.
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 the webMethods Broker Client Java API Programmer’s Guide for more information on client identifiers.
client_group The name of the client group for the new Broker client. Client groups are discussed in Administering webMethods Broker.
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 may be shared with other Broker clients.
Possible Exceptions Meaning
BrokerInvalidClientException The BrokerAdminClient has been destroyed or disconnected.
BrokerNullParameterException The client parameter is null.
360 webMethods Broker Administration Java API Programmer’s Guide Version 8.2
12 Java API Administration Reference
Returns a BrokerCompleteServer object containing information on the Broker Server to which the administrative Broker client is connected.
All Brokers which this client has permission to access will be set in the data members client_groups and event_types data members, using the BrokerCompleteBroker.deepRetrieve. Any information which the client does not have permission to read will be set to null.
The client_id, client_group, app_name, and desc are all used to establish individual connections to each Broker in the brokers array. Any information that the client does not have permission to read will be set to null. For more information, see BrokerAdminClient.
See Also:
BrokerCompleteServer.retrieve
deepStore
void deepStore( BrokerAdminClient client) String client_id, String client_group, String app_name, BrokerConnectionDescriptor desc) throws BrokerException
client The administrative client to be used to retrieve contents for this object.
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 the webMethods Broker Client Java API Programmer’s Guide for more information on client identifiers.
client_group The name of the client group for the new Broker client. Client groups are discussed in Administering webMethods Broker.
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 may be shared with other Broker clients.
Possible Exceptions Meaning
BrokerInvalidClientException The BrokerAdminClient has been destroyed or disconnected.
BrokerNullParameterException The client parameter is null.
client The administrative client to be used to store this object.
webMethods Broker Administration Java API Programmer’s Guide Version 8.2 361
12 Java API Administration Reference
Stores the information from this object into the Broker Server to which the client is connected. The host_name member in this object is ignored, but other values may be overwritten or merged.
If the description is set, it will replace the existing value.
If the port is set to a non-zero value, it will replace the existing port value.
If the log_config is set, it will replace the existing logging configuration.
If the ssl_config is set, it will replace the existing SSL configuration.
If the acl is set, it will replace the existing access control list.
If any Brokers are set in the brokers data member, they will each be stored using the BrokerCompleteBroker.deepStore method. If a Broker by that name does not already exist, a new one will be created.
If any Broker that is stored is not already in a territory and its brokers_in_territory field is set, an attempt will be made to join to the territory of the first Broker in the list. If territory_name is set, but no brokers_in_territory are listed, then a new territory will be created for the Broker. Errors from the joining or creation of a territory are ignored.
The client_id, client_group, app_name, and desc are all used to establish individual connections to each Broker in the brokers array. Any information that the client does not have permission to read will be set to null. For more information, see BrokerAdminClient.
If an exception occurs while storing the host information, nothing will be updated. If storage of the host information succeeds, each Broker is handled in the order in which they occur in the brokers array. If an exception is thrown at that point, only that Broker (and subsequent Brokers in the array), will not be change.
Only the host information and the Brokers for which storage succeeded will have been changed.
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 the webMethods Broker Client Java API Programmer’s Guide for more information on client identifiers.
client_group The name of the client group for the new Broker client. Client groups are discussed in Administering webMethods Broker.
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 may be shared with other Broker clients.
362 webMethods Broker Administration Java API Programmer’s Guide Version 8.2
12 Java API Administration Reference
See Also:
BrokerCompleteServer.store
refresh
void refresh( BrokerAdminClient client) throws BrokerException
Refreshes this object's Broker Server information, based on the specified administrative Broker client. Any host information that the client does not have permission to read will be set to null.
See Also:
BrokerCompleteServer.deepRefresh
retrieve
static BrokerCompleteServer retrieve( BrokerAdminClient client) throws BrokerException
Returns a BrokerCompleteServer object containing information on the host to which the administrative Broker client is connected. Retrieves the server information, but not information for Brokers.
Possible Exceptions Meaning
BrokerInvalidClientException The BrokerAdminClient has been destroyed or disconnected.
BrokerNoPermissionException The client does not have permission to change the Broker's configuration.
BrokerNullParameterException client, client_group, or app_name parameter is null.
client The administrative client to be used to refresh this object.
Possible Exceptions Meaning
BrokerInvalidClientException The BrokerAdminClient has been destroyed or disconnected.
BrokerNullParameterException The client parameter is null.
client The administrative client to be used to retrieve contents for this object.
webMethods Broker Administration Java API Programmer’s Guide Version 8.2 363
12 Java API Administration Reference
See Also:
BrokerCompleteServer.deepRetrieve
store
void store( BrokerAdminClient client) throws BrokerException
Stores the information from this object into the Broker to which the client is connected.
The host name in this object is ignored, but other values may be overwritten or merged.
If the description is set, it will replace the existing value.
If the port is set to something other than zero, it will replace the existing port number.
If the log_config is set, it will replace the existing logging configuration.
If the ssl_config is set, it will replace the existing SSL configuration.
If the acl is set, it will replace the existing access control list.
The Brokers contained in brokers will not be stored under this host. These must be stored separately by using the BrokerCompleteBroker.store or BrokerCompleteBroker.deepStore method. You may also use the BrokerCompleteServer.deepStore method to store all of the host information, including the Brokers.
If an exception is thrown, none of the host's information will be modified.
See Also:
BrokerCompleteServer.deepStore
Possible Exceptions Meaning
BrokerInvalidClientException The BrokerAdminClient has been destroyed or disconnected.
BrokerNullParameterException The client parameter is null.
client The administrative client to be used to store the Broker information.
Possible Exceptions Meaning
BrokerInvalidClientException The BrokerAdminClient has been destroyed or disconnected.
BrokerNoPermissionException The client does not have permission to change the Broker's configuration.
BrokerNullParameterException The client parameter is null.
364 webMethods Broker Administration Java API Programmer’s Guide Version 8.2
12 Java API Administration Reference
toString
String toString()
Converts the information contained in this object into a string in ADL format that may be saved to a file. For more information on ADL, see Administering webMethods Broker.
Returns an empty string if all of the data members are null or if their conversion results in an empty string.
toString
String toString( int indent_level) throws BrokerException
Converts the information contained in this object into a string in ADL format that may be saved to a file. For more information on ADL, see Administering webMethods Broker.
Returns an empty string if all of the data members are null or if their conversion results in an empty string.
write
void write( Writer writer, int indent_level) throws BrokerException, IOException
Writes out this object's Broker information in ADL format, usually to a file. No data will be written if the broker_name is null.
For more information on ADL, see Administering webMethods Broker.
indent_level The number of 4-character spaces to use for indentation.
Possible Exceptions Meaning
BrokerOutOfRangeException The indent_level parameter is less than 0.
writer The file where the data is to be written.
indent_level The number of 4-character spaces to use for indentation.
Possible Exceptions Meaning
IOException There was an error writing the data to the file.
BrokerNullParameterException The writer parameter is null.
BrokerOutOfRangeException The indent_level parameter is less than 0.
webMethods Broker Administration Java API Programmer’s Guide Version 8.2 365
12 Java API Administration Reference
BrokerCompleteTerritory
class BrokerCompleteTerritory extends java.lang.Object
This class represents all configuration information for a Broker territory and is used to load, save, import or export the territory's configuration. In particular, this class contains the access control lists defined for the territory. This class also uses the BrokerTerritoryInfo class.
See “Managing Broker Territories” on page 93 for more information on territories.
Variables
acl
BrokerAccessControlList acl
Contains the access control list for the Broker territory.
info
BrokerTerritoryInfo info
Contains information on the territory itself. For more information, see BrokerTerritoryInfo on page 456.
other_brokers_in_territory
BrokerInfo other_brokers_in_territory[]
Contains the names of the other Broker that are in this territory.
Constructors
BrokerCompleteTerritory
BrokerCompleteTerritory()
Creates an empty BrokerCompleteTerritory object.
BrokerCompleteTerritory
BrokerCompleteTerritory( BrokerTerritoryInfo info)
Creates a territory object, setting the info variable in the process.
info The territory information to set in the newly created object.
366 webMethods Broker Administration Java API Programmer’s Guide Version 8.2
12 Java API Administration Reference
Methods
refresh
void refresh( BrokerAdminClient client) throws BrokerException
Refreshes this object's Broker territory information, based on the specified administrative Broker client. Any information that the client does not have permission to read will be set to null.
See Also:
BrokerCompleteTerritory.retrieve
retrieve
static BrokerCompleteTerritory retrieve( BrokerAdminClient client) throws BrokerException
Returns a BrokerCompleteTerritory object containing information on the host to which the administrative Broker client is connected. Retrieves the server information, but not information for Brokers.
See Also:
BrokerCompleteTerritory.store
client The administrative client to be used to refresh this object.
Possible Exceptions Meaning
BrokerInvalidClientException The BrokerAdminClient has been destroyed or disconnected.
BrokerNullParameterException The client parameter is null.
client The administrative client to be used to retrieve contents for this object.
Possible Exceptions Meaning
BrokerInvalidClientException The BrokerAdminClient has been destroyed or disconnected.
BrokerNullParameterException The client parameter is null.
webMethods Broker Administration Java API Programmer’s Guide Version 8.2 367
12 Java API Administration Reference
store
void store( BrokerAdminClient client) throws BrokerException
Stores the territory information from this object into the Broker to which the client is connected.
If the Broker does not belong to the territory, then an attempt to locate it is made, using the other_brokers_in_territory list. If the territory cannot be found, it will be created.
If the territory already existed, then all of its information will be overwritten.
The auth_type and encrypt_level in the info member will replace the current settings in the territory.
If the access control list is set, it will replace the existing acl.
If an exception is thrown, none of the territory's information will be modified.
See Also:
BrokerCompleteTerritory.retrieve
toString
String toString()
Converts the information contained in this object into a string in ADL format that may be saved to a file. For more information on ADL, see Administering webMethods Broker.
Returns an empty string if all of the data members are null or if their conversion results in an empty string.
toString
String toString( int indent_level) throws BrokerException
client The administrative client to be used to store the Broker territory information.
Possible Exceptions Meaning
BrokerInvalidAccessListException The acl variable does not contain a valid access control list.
BrokerInvalidClientException The BrokerAdminClient has been destroyed or disconnected.
BrokerNullParameterException The client parameter is null or the variable info or info.territory_name are null
368 webMethods Broker Administration Java API Programmer’s Guide Version 8.2
12 Java API Administration Reference
Converts the information contained in this object into a string in ADL format that may be saved to a file. For more information on ADL, see Administering webMethods Broker.
Returns an empty string if all of the data members are null or if their conversion results in an empty string.
write
void write( Writer writer, int indent_level) throws BrokerException, IOException
Writes out this object's territory information in ADL format, usually to a file. No data will be written if the info member is null.
For more information on ADL, see Administering webMethods Broker.
BrokerCompleteTerritoryGateway
class BrokerCompleteTerritoryGateway extends java.lang.Object
This class represents all configuration information for a territory gateway and is used to load, save, import or export the gateway's configuration. In particular, this class contains the access control lists defined for the territory. This class also uses the BrokerTerritoryGatewayInfo class.
See “Managing Broker Territories” on page 93 for more information on territories.
indent_level The number of 4-character spaces to use for indentation.
Possible Exceptions Meaning
BrokerOutOfRangeException The indent_level parameter is less than 0.
writer The file where the data is to be written.
indent_level The number of 4-character spaces to use for indentation.
Possible Exceptions Meaning
IOException There was an error writing the data to the file.
BrokerNullParameterException The writer parameter is null.
BrokerOutOfRangeException The indent_level parameter is less than 0.
webMethods Broker Administration Java API Programmer’s Guide Version 8.2 369
12 Java API Administration Reference
Variables
acl
BrokerAccessControlList acl
Contains the access control list for the territory gateway.
info
BrokerTerritoryGatewayInfo info
Contains information on the territory gateway itself. For more information, see BrokerTerritoryGatewayInfo on page 453.
remote_can_publish
String remote_can_publish[]
Contains the names of all the shared event types that can be forwarded to the remote half of the territory gateway.
remote_can_subscribe BrokerSubscription remote_can_subscribe[]
Contains the subscriptions for all of the shared event types that can be received from the remote half of the territory gateway.
Constructors
BrokerCompleteTerritoryGateway
BrokerCompleteTerritoryGateway()
Creates an empty BrokerCompleteTerritory object.
BrokerCompleteTerritory
BrokerCompleteTerritoryGateway( BrokerTerritoryGatewayInfo info)
Creates a territory gateway object, setting the info variable in the process.
info The gateway information to set in the newly created object.
370 webMethods Broker Administration Java API Programmer’s Guide Version 8.2
12 Java API Administration Reference
Methods
refresh
void refresh( BrokerAdminClient client) throws BrokerException
Refreshes this object's territory gateway information, based on the specified administrative Broker client. Any information that the client does not have permission to read will be set to null.
See Also:
BrokerCompleteTerritoryGateway.retrieve
retrieve
static BrokerCompleteTerritoryGateway retrieve( BrokerAdminClient client) throws BrokerException
Returns a BrokerCompleteTerritory object containing information on the host to which the administrative Broker client is connected. Retrieves the server information, but not information for Brokers.
client The administrative client to be used to refresh this object.
Possible Exceptions Meaning
BrokerInvalidClientException The BrokerAdminClient has been destroyed or disconnected.
BrokerNotInTerritory The Broker to which client is connected is not part of a territory.
BrokerNullParameterException The client parameter is null or the variable info or info.remote_territory_name is null.
BrokerUnknownTerritoryException There is no gateway to the specified territory from this Broker.
client The administrative client to be used to retrieve contents for this object.
Possible Exceptions Meaning
BrokerInvalidClientException The BrokerAdminClient has been destroyed or disconnected.
BrokerNotInTerritory The Broker to which client is connected is not part of a territory.
webMethods Broker Administration Java API Programmer’s Guide Version 8.2 371
12 Java API Administration Reference
See Also:
BrokerCompleteTerritoryGateway.store
store
void store( BrokerAdminClient client) throws BrokerException
Stores the territory gateway information from this object into the Broker to which the client is connected.
First, the existence of a gateway to the remote territory is confirmed. If such a gateway does not exist, it will be created.
Any other gateways that are already configured for the Broker will not be changed.
Only the following BrokerTerritoryGatewayInfo members are modified by this method:
remote_territory_name
remote_host_name
remote_broker_name
auth_type
encrypt_level
All specifics about a territory gateway will be overwritten.
The auth_type and encrypt_level in the info member will replace the current settings for the gateway.
If acl is set, it will replace the existing access control list.
If either remote_can_publish or remote_can_subscribe are not null, this gateway's shared event type list will be replaced. In these cases, the sub_id fields in the remote_can_subscribe array will be ignored.
If an exception is thrown, none of the gateway information will be modified.
BrokerNullParameterException The client parameter is null.
BrokerUnknownTerritoryException There is no gateway to the specified territory from this Broker.
client The administrative client to be used to store the Broker territory information.
Possible Exceptions Meaning
372 webMethods Broker Administration Java API Programmer’s Guide Version 8.2
12 Java API Administration Reference
See Also:
BrokerCompleteTerritoryGateway.retrieve
toString
String toString()
Converts the information contained in this object into a string in ADL format that may be saved to a file. For more information on ADL, see Administering webMethods Broker.
Returns an empty string if all of the data members are null or if their conversion results in an empty string.
toString
String toString( int indent_level) throws BrokerException
Converts the information contained in this object into a string in ADL format that may be saved to a file. For more information on ADL, see Administering webMethods Broker.
Returns an empty string if all of the data members are null or if their conversion results in an empty string.
Possible Exceptions Meaning
BrokerInvalidAccessListException The acl variable does not contain a valid access control list.
BrokerInvalidClientException The BrokerAdminClient has been destroyed or disconnected.
BrokerNullParameterException The client parameter is null.
BrokerOutOfRangeException Either the specified gateway already exists and was established by another Broker in this Broker's territory or it has a different remote Broker. If this exception is thrown, the gateway is not altered.
BrokerUnknownBrokerNameException The other half of the gateway has not been established and the remote Broker could not be found.
indent_level The number of 4-character spaces to use for indentation.
Possible Exceptions Meaning
BrokerOutOfRangeException The indent_level parameter is less than 0.
webMethods Broker Administration Java API Programmer’s Guide Version 8.2 373
12 Java API Administration Reference
write
void write( Writer writer, int indent_level) throws BrokerException, IOException
Writes out this object's gateway information in ADL format, usually to a file. No data will be written if the info member is null.
For more information on ADL, see Administering webMethods Broker.
BrokerFilterDescriptor
class BrokerFilterDescriptor extends java.lang.Object
This class represents a Broker filter setting. Queue browsers use this class to set filters for browse operation. For more information about using queue browser filters, see “Filters on a Queue Browser” on page 154.
Variables
eventTypeName
String eventTypeName
Contains the document type name.
filterExpr
String filterExpr
Contains the filter expression.
writer The file where the data is to be written.
indent_level The number of 4-character spaces to use for indentation.
Possible Exceptions Meaning
IOException There was an error writing the data to the file.
BrokerNullParameterException The writer parameter is null.
BrokerOutOfRangeException The indent_level parameter is less than 0.
374 webMethods Broker Administration Java API Programmer’s Guide Version 8.2
12 Java API Administration Reference
Constructors
BrokerFilterDescriptor
BrokerFilterDescriptor()
Creates an empty filter descriptor.
BrokerFilterDescriptor
BrokerFilterDescriptor( String event_type_name, String filter_expr filter)
Creates a BrokerFilterDescriptor object, setting the eventTypeName and filterExpr to the values specified.
Methods
toString
String toString()
Returns a string containing the filter in a human-readable format.
BrokerForwardQueueBrowserclass BrokerForwardQueueBrowser implements BrokerQueueBrowser
This class provides queue browsing capabilities to view events in the forwarding queue.
Methods
browseEvents
BrokerEvent[] browseEvents( int max_events, int msecs) throws BrokerException
Browses the queue and returns one or more events from the forwarding queue. Returns immediately with one of the following:
event_type_name Document name
filter_expr filter Expression
webMethods Broker Administration Java API Programmer’s Guide Version 8.2 375
12 Java API Administration Reference
An array of events if found. The number of events being returned is not guaranteed to be max_events even if there are more than max_events in the queue. Any number of events up to the value of max_events may be returned.
An error if the end of queue is reached. 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.
In addition to the listed exceptions, any communications exception can be thrown.
closeQueueBrowser
void closeQueueBrowser() throws BrokerException
Closes the current forwarding queue browser object; otherwise throws Broker exception.
getBrowserInfo
BrokerQueueBrowserInfo getBrowserInfo() throws BrokerException
Gets information about the current forwarding queue browser. Returns a BrokerQueueBrowserInfo object.
getFilters
void getFilters() throws BrokerException
Possible Exceptions Meaning
BrokerTimeoutException The timeout is reached before an event arrives.
BrokerOutOfRangeException The max_events or msecs parameter is less than zero.
BrokerQueueBrowserException The queue browser is invalid.
BrokerQueueBrowserException The event at the last cursor position was removed. Reset the cursor to a valid position before attempting a browse operation.
BrokerQueueBrowserException The queue is busy; retry the operation later.
BrokerQueueBrowserException The queue is empty and no more events can be returned. For forwarding queues, this exception might be thrown when there are only internal events within the requested browsing range.
BrokerInvalidClientException The client has been destroyed or is disconnected.
Possible Exceptions Meaning
BrokerQueueBrowserException The queue browser is invalid.
376 webMethods Broker Administration Java API Programmer’s Guide Version 8.2
12 Java API Administration Reference
Returns the filters set on the forwarding queue browser.
resetFilters
void resetFilters() throws BrokerException
Removes the filters set on the queue browser. Any subsequent browse requests would consider all the events in the queue.
setFilter
void setFilter( BrokerFilterDescriptor filter) throws BrokerException
Sets the filter for queue browser's browse operation. Any subsequent browse requests would return only those events that satisfy the filter condition. If a filter for the specified document type already exists on the queue browser, it will be overwritten with the new filter setting.
setFilters
void setFilters( BrokerFilterDescriptor filters) throws BrokerException
Sets filters for forwarding queue browser's browse operation. Any subsequent browse requests would return only those events that satisfy the filter condition. If a filter for the specified document type already exists on the queue browser, it will be overwritten with the new filter setting.
Possible Exceptions Meaning
BrokerQueueBrowserException The queue browser is invalid.
Possible Exceptions Meaning
BrokerQueueBrowserException The queue browser is invalid.
Possible Exceptions Meaning
BrokerQueueBrowserException The queue browser is invalid.
BrokerFilterParseException An error occurred while parsing the filter expression
BrokerInvalidFilterException The specified filter expression on the filter object is invalid.
BrokerNullParameterException The filter parameter is null or the filter expression on the BrokerFilterDescriptor is null.
BrokerUnknownEventTypeException The specified event type on the filter object does not exist on the Broker.
webMethods Broker Administration Java API Programmer’s Guide Version 8.2 377
12 Java API Administration Reference
setPosition
void setPosition( int position) throws BrokerException
Set the browser's cursor position to the specified position on the forwarding queue, where a value of '0' represents the head of the queue and a value of "queue length minus one" represents the end of the queue. Valid position values are in the range of 0 and "queue length-1".
BrokerInfo
class BrokerInfo extends java.lang.Object
This class contains a description of a Broker, including its name.
Variables
broker_host
String broker_host
Contains the Broker's host name.
broker_name
String broker_name
Contains the Broker's name.
cluster_name
String cluster_name
Possible Exceptions Meaning
BrokerQueueBrowserException The queue browser is invalid.
BrokerFilterParseException An error occurred while parsing the filter expression
BrokerInvalidFilterException The specified filter expression on the filter object is invalid.
BrokerNullParameterException The filters parameter is null or the filter expression on the BrokerFilterDescriptor is null.
BrokerUnknownEventTypeException The specified event type on the filter object does not exist on the Broker.
378 webMethods Broker Administration Java API Programmer’s Guide Version 8.2
12 Java API Administration Reference
Contains the cluster's name.
description
String description
Contains the Broker's description.
territory_name
String territory_name
Contains the Broker's name.
Constructors
BrokerInfo
BrokerInfo()
Creates a BrokerInfo object without setting the name or description.
BrokerInfo
BrokerInfo( String territory, String host, String name, String description)
Creates a BrokerInfo object, setting the territory_name, broker_host, broker_name, and description to the values specified.
Note: For information on territory and Broker name restrictions, see the webMethods Broker Client Java API Programmer’s Guide.
BrokerJoinFailureInfo
class BrokerJoinFailureInfo extends java.lang.Object
territory The Broker's territory.
host The Broker's host name.
name The Broker's name.
description The Broker's description.
webMethods Broker Administration Java API Programmer’s Guide Version 8.2 379
12 Java API Administration Reference
This class is used to report failures from the BrokerAdminClient.joinTerritory method. It contains a list of any client groups or event types that conflicted with the territory. See “Managing Broker Territories” on page 93 for more information on territories.
Variables
client_group_names
String client_group_names[]
Contains the names of all the Broker's client groups whose definitions conflicted with the territory's definitions.
event_type_names
String event_type_names[]
Contains the names of all the Broker's event types whose definitions conflicted with the territory's definitions.
ConstructorsBrokerJoinFailure()
Creates an empty BrokerJoinFailure object.
BrokerLockedClientQueueBrowser
See Also:
BrokerLockedForwardQueueBrowser
class BrokerLockedClientQueueBrowser extends BrokerClientQueueBrowser
This class provides extended queue browsing capabilities to re-arrange the contents of a client queue.
Methods
deleteEvents
int deleteEvents( long[] seqns) throws BrokerException
380 webMethods Broker Administration Java API Programmer’s Guide Version 8.2
12 Java API Administration Reference
Deletes events with the specified receipt sequence numbers from the client queue. Returns the number of events successfully deleted from the queue. The presence of invalid sequence numbers (zero or a value less than zero) or duplicate sequence numbers would result in an error. You can use a delete request to remove unacknowledged events from the queue.
insertEventsAtHead
void insertEventsAtHead( BrokerEvent[] events) throws BrokerException
Inserts events into the client queue at the head position (queue position of zero).
insertEventsAtTail
void insertEventsAtTail( BrokerEvent[] events) throws BrokerException
Possible Exceptions Meaning
BrokerClientQueueBrowserException The queue browser is invalid.
BrokerClientQueueBrowserException A receipt sequence number of value zero is specified, which is not a valid receipt sequence number.
BrokerClientQueueBrowserException The client queue is busy; retry the operation.
BrokerInvalidSequenceNumberException No event was found on the client queue for one or more of the specified receipt sequence numbers.
BrokerNullParameterException The seqns parameter is null or of array length zero.
BrokerOutOfRangeException A duplicate sequence number is found on the array.
Possible Exceptions Meaning
BrokerClientQueueBrowserException The queue browser is invalid.
BrokerInvalidEventException One or more of the specified event is invalid.
BrokerNoPermissionException The target client queue does not have permission to subscribe to one or more of the specified events.
BrokerNullParameterException The events parameter is null or of array length zero or one of the array element is null.
webMethods Broker Administration Java API Programmer’s Guide Version 8.2 381
12 Java API Administration Reference
Inserts events into the client queue at the tail position (queue position "queue length minus one").
modifyEvents
int modifyEvents( long[] seqns) throws BrokerException
Modifies events in the queue. Events with the specified receipt sequence numbers in the client queue will be replaced with the specified events. The presence of invalid sequence numbers (zero or a value less than zero) or duplicate sequence numbers would result in an error. Any attempt to modify an event that is unacknowledged would also result in an error. Note that the storage type of the replaced and replacing events should match; any mismatch would be raised as an exception.
Possible Exceptions Meaning
BrokerClientQueueBrowserException The queue browser is invalid.
BrokerInvalidEventException One or more of the specified event is invalid.
BrokerNoPermissionException The target client does not have permission to subscribe to one or more of the specified events.
BrokerNullParameterException The events parameter is null or of array length zero or one of the array element is null.
Possible Exceptions Meaning
BrokerClientQueueBrowserException The queue browser is invalid.
BrokerClientQueueBrowserException A receipt sequence number of value zero is specified, which is not a valid receipt sequence number.
BrokerClientQueueBrowserException The client queue is busy; retry the operation.
BrokerClientQueueBrowserException The storage types of replaced and replacing events do not match.
BrokerClientQueueBrowserException The event cannot be modified as it has already been retrieved by the client session and is not yet acknowledged, i.e., the event is an "unacknowledged" event.
BrokerInvalidSequenceNumberException No event was found on the client queue for one or more of the specified receipt sequence numbers.
BrokerNullParameterException The seqns or the events parameter is null or of array length zero.
382 webMethods Broker Administration Java API Programmer’s Guide Version 8.2
12 Java API Administration Reference
BrokerLockedForwardQueueBrowser
class BrokerLockedForwardQueueBrowser extends BrokerForwardQueueBrowser implements BrokerLockedQueueBrowser
This class extends queue browsing capabilities of BrokerForwardQueueBrowser to view the contents of a forwarding queue in the locked mode.
Methods
deleteEvents
int deleteEvents( long[] seqns) throws BrokerException
Deletes regular events with the specified receipt sequence numbers from the forwarding queue. Returns the number of events successfully deleted from the forwarding queue. The presence of invalid sequence numbers (zero or a value less than zero) or duplicate sequence numbers would result in an error. You can use a delete request to remove unacknowledged events from the queue.
BrokerOutOfRangeException A duplicate sequence number is found on the array
Possible Exceptions Meaning
BrokerQueueBrowserException The queue browser is invalid.
BrokerQueueBrowserException A receipt sequence number of value zero is specified, which is not a valid receipt sequence number.
BrokerQueueBrowserException The forwarding queue is busy; retry the operation.
BrokerInvalidSequenceNumberException No event was found on the forwarding queue for one or more of the specified receipt sequence numbers.
BrokerNullParameterException The seqns parameter is null or of array length zero.
BrokerOutOfRangeException A duplicate sequence number is found on the array.
Possible Exceptions Meaning
webMethods Broker Administration Java API Programmer’s Guide Version 8.2 383
12 Java API Administration Reference
insertEventsAtTail
void insertEventsAtTail( BrokerEvent[] events) throws BrokerException
Inserts events into the forwarding queue at the tail position (queue position "queue length minus one").
Note: webMethods Broker Java API does not support the "insert events at head" operation although the "insertEventsAtHead" API is available to do so. Invoking the insertEventsAtHead API throws an "unsupported operation" exception.
modifyEvents
void modifyEvents( long[] seqns, BrokerEvent[] events) throws BrokerException
Modifies events in the forwarding queue. Events with the specified receipt sequence numbers in the forwarding queue will be replaced with the specified events. The presence of invalid sequence numbers (zero or a value less than zero) or duplicate sequence numbers would result in an error. Any attempt to modify an event that is unacknowledged would also result in an error. Note that the storage type of the replaced and replacing events should match; any mismatch would be raised as an exception.
Possible Exceptions Meaning
BrokerQueueBrowserException The queue browser is invalid.
BrokerInvalidEventException One or more of the specified events is invalid.
BrokerNullParameterException The events parameter is null or of array length zero or one of the array element is null.
Possible Exceptions Meaning
BrokerQueueBrowserException The queue browser is invalid.
BrokerQueueBrowserException A receipt sequence number of value zero is specified, which is not a valid receipt sequence number.
BrokerQueueBrowserException The queue is busy; retry the operation.
BrokerQueueBrowserException The storage types of replaced and replacing events do not match.
BrokerQueueBrowserException The event cannot be modified as it has already been retrieved and is not yet acknowledged, i.e., the event is an "unacknowledged" event.
384 webMethods Broker Administration Java API Programmer’s Guide Version 8.2
12 Java API Administration Reference
BrokerLockedQueueBrowser
interface BrokerLockedQueueBrowser extends BrokerQueueBrowser
This interface provides queue browsing capabilities to view and modify the contents of a queue.
Methods
deleteEvents
int deleteEvents( long[] seqns) throws BrokerException
Deletes events with the specified receipt sequence numbers from the queue. Returns the number of events successfully deleted from the queue. The presence of invalid sequence numbers (zero or a value less than zero) or duplicate sequence numbers would result in an error. You can use a delete request to remove unacknowledged events from the queue.
BrokerQueueBrowserException Invalid input arguments. Means that the array length of sequence number is not equal to the array length of events.
BrokerInvalidSequenceNumberException No event was found on the queue for one or more of the specified receipt sequence numbers.
BrokerNullParameterException The seqns or the events parameter is null or of array length zero.
BrokerOutOfRangeException A duplicate sequence number is found on the array
Possible Exceptions Meaning
BrokerQueueBrowserException The queue browser is invalid.
BrokerQueueBrowserException A receipt sequence number of value zero is specified, which is not a valid receipt sequence number.
BrokerQueueBrowserException The client queue is busy; retry the operation.
BrokerInvalidSequenceNumberException No event was found on the queue for one or more of the specified receipt sequence numbers.
Possible Exceptions Meaning
webMethods Broker Administration Java API Programmer’s Guide Version 8.2 385
12 Java API Administration Reference
insertEventsAtHead
void insertEventsAtHead( BrokerEvent[] events) throws BrokerException
Inserts events into the client queue at the head position (queue position of zero).
insertEventsAtTail
void insertEventsAtTail( BrokerEvent[] events) throws BrokerException
Inserts events into the queue at the tail position (queue position "queue length minus one").
BrokerNullParameterException The seqns parameter is null or of array length zero.
BrokerOutOfRangeException A duplicate sequence number is found on the array.
Possible Exceptions Meaning
BrokerQueueBrowserException The queue browser is invalid.
BrokerInvalidEventException One or more of the specified event is invalid.
BrokerNoPermissionException The target client or remote Broker's forwarding queue does not have permission to subscribe to one or more of the specified events.
BrokerNullParameterException The events parameter is null or of array length zero or one of the array element is null.
events An array of events that you want to insert into the queue.
Possible Exceptions Meaning
BrokerQueueBrowserException The queue browser is invalid.
BrokerInvalidEventException One or more of the specified event is invalid.
BrokerNoPermissionException The target client does not have permission to subscribe to one or more of the specified events.
BrokerNullParameterException The events parameter is null or of array length zero or one of the array element is null.
Possible Exceptions Meaning
386 webMethods Broker Administration Java API Programmer’s Guide Version 8.2
12 Java API Administration Reference
modifyEvents
void modifyEvents( long[] seqns), BrokerEvent[] events) throws BrokerException
Modifies events in the queue. Events with the specified receipt sequence numbers in the queue will be replaced with the specified events. The presence of invalid sequence numbers (zero or a value less than zero) or duplicate sequence numbers would result in an error. Any attempt to modify an event that is unacknowledged would also result in an error. Note that the storage type of the replaced and replacing events should match; any mismatch would be raised as an exception.
BrokerLogConfig
class BrokerLogConfig extends java.lang.Object
seqns An array of sequence numbers that identify the events to be modified in the queue
events An array of BrokerEvent that will be updated in place of the events in the queue.
Possible Exceptions Meaning
BrokerQueueBrowserException The queue browser is invalid.
BrokerQueueBrowserException A receipt sequence number of value zero is specified, which is not a valid receipt sequence number.
BrokerQueueBrowserException The queue is busy; retry the operation.
BrokerQueueBrowserException The storage types of replaced and replacing events do not match.
BrokerQueueBrowserException The event cannot be modified as it has already been retrieved by the client session and is not yet acknowledged, i.e., the event is an "unacknowledged" event.
BrokerInvalidSequenceNumberException No event was found on the client queue for one or more of the specified receipt sequence numbers.
BrokerNullParameterException The seqns or the events parameter is null or of array length zero.
BrokerOutOfRangeException A duplicate sequence number is found on the array.
webMethods Broker Administration Java API Programmer’s Guide Version 8.2 387
12 Java API Administration Reference
This class provides methods for configuring the log output produced by a Broker. The BrokerLogConfig supports three different levels of message logging:
In addition, the BrokerLogConfig supports any of these mechanisms for logging events:
UNIX syslog facility
Windows NT event log
SNMP alerts.
Variables
LOG_OUTPUT_NT_EVENT_LOG
LOG_OUTPUT_SNMP_TRAP
LOG_OUTPUT_UNIX_SYSLOG
LOG_TOPIC_ALERT
LOG_TOPIC_INFO
LOG_TOPIC_WARNING
Constructors
BrokerLogConfig
BrokerLogConfig()
Creates a log configuration object with all logging disabled.
BrokerLogConfig
BrokerLogConfig( BrokerLogConfig log_config) throws BrokerException
Constructor that makes a new log configuration object that is a copy of log_config.
Level Description
Alert Identifies critical messages.
Warning Identifies important messages.
Informational Identifies informational messages.
log_config The object being copied.
388 webMethods Broker Administration Java API Programmer’s Guide Version 8.2
12 Java API Administration Reference
Methods
clearLogOutput
void clearLogOutput( String code) throws Brokerexception
Deletes one entry from the specified log output.
See Also:
BrokerLogConfig.clearLogOutputs
clearLogOutputs
void clearLogOutputs()
Deletes all entries from all log outputs.
See:
BrokerLogConfig.clearLogOutput.
clearLogTopic
void clearLogTopic( String code) throws BrokerException
Possible Exceptions Meaning
BrokerNullParameterException The log_config parameter is null.
code Specifies the log output that is to be cleared. Must be one of the following values:
LOG_OUTPUT_UNIX_SYSLOG
LOG_OUTPUT_NT_EVENT_LOG
LOG_OUTPUT_SNMP_TRAP
Possible Exceptions Meaning
BrokerNullParameterException The code parameter is null.
webMethods Broker Administration Java API Programmer’s Guide Version 8.2 389
12 Java API Administration Reference
Deletes one entry from a single log topic.
See Also:
BrokerLogConfig.clearLogTopics
clearLogTopics
void clearLogTopics()
Deletes all entries from all log topics.
See:
BrokerLogConfig.clearLogTopic
getLogOutput
BrokerLogConfigEntry getLogOutput( String code) throws BrokerException
Returns the state of the specified log output. For more information, see BrokerLogConfigEntry.
code Specifies the log topic that is to be cleared. Must be one of the following values:
LOG_TOPIC_ALERT
LOG_TOPIC_INFO
LOG_TOPIC_WARNING
Possible Exceptions Meaning
BrokerNullParameterException The code parameter is null.
code Specifies the log output whose state is to be returned. Must be one of the following values:
LOG_OUTPUT_UNIX_SYSLOG
LOG_OUTPUT_NT_EVENT_LOG
LOG_OUTPUT_SNMP_TRAP
Possible Exceptions Meaning
BrokerNullParameterException The code parameter is null.
BrokerOutOfRangeException The code parameter is not in this log configuration.
390 webMethods Broker Administration Java API Programmer’s Guide Version 8.2
12 Java API Administration Reference
See Also:
BrokerLogConfig.getLogOutputs, BrokerLogConfig.setLogOutput, and BrokerLogConfig.setLogOutput
getLogOutputs
BrokerLogConfigEntry[] getLogOutputs()
Returns an array of BrokerLogConfigEntry object containing the state of the each log output.
See:
BrokerLogConfig.getLogOutput, BrokerLogConfig.setLogOutput, BrokerLogConfig.setLogOutput
getLogTopic
BrokerLogConfigEntry getLogTopic( String log_topic) throws BrokerException
Returns the state of the specified log topic. See BrokerLogConfigEntry on page 394 for more information.
See Also:
BrokerLogConfig.getLogTopics and BrokerLogConfig.setLogTopic
getLogTopics
BrokerLogConfigEntry[] getLogTopics()
Returns an array of BrokerLogConfigEntry object containing the state of each log topic. See BrokerLogConfigEntry on page 394 for more information.
See:
BrokerLogConfig.getLogTopic and BrokerLogConfig.setLogTopic
log_topic Specifies the log topic whose state is to be returned. Must be one of the following values:
LOG_TOPIC_ALERT
LOG_TOPIC_WARNING
LOG_TOPIC_INFO
Possible Exceptions Meaning
BrokerNullParameterException The code parameter is null.
BrokerOutOfRangeException The code parameter is not set in this log configuration.
webMethods Broker Administration Java API Programmer’s Guide Version 8.2 391
12 Java API Administration Reference
setLogOutput
void setLogOutput( BrokerLogConfigEntry log_output) throws BrokerException
Sets the value of a single log topic to the specified state. See BrokerLogConfigEntry on page 394 for more information.
See Also:
BrokerLogConfig.getLogOutput, BrokerLogConfig.getLogOutputs, BrokerLogConfig.setLogOutput
setLogOutput
void setLogOutput( String code, boolean enabled, String value) throws BrokerException
Sets or creates a single log output state.
See BrokerLogConfigEntry on page 394 for more information.
See Also:
BrokerLogConfig.getLogOutput, BrokerLogConfig.getLogOutputs, BrokerLogConfig.setLogOutput
log_output Specifies the type and state of log output that is to be set.
Possible Exceptions Meaning
BrokerNullParameterException log_output parameter or log_output.code is null.
code Specifies the log output whose state is to be set. Must be one of the following values:
LOG_OUTPUT_UNIX_SYSLOG
LOG_OUTPUT_NT_EVENT_LOG
LOG_OUTPUT_SNMP_TRAP
enabled If set to true, this output is enabled.
value The value to be set. Usually set to null.
Possible Exceptions Meaning
BrokerNullParameterException The code parameter is null.
392 webMethods Broker Administration Java API Programmer’s Guide Version 8.2
12 Java API Administration Reference
setLogTopic
void setLogTopic( BrokerLogConfigEntry log_topic) throws BrokerException
Sets the value of a single log topic's state.
See BrokerLogConfigEntry on page 394 for more information.
See Also:
BrokerLogConfig.getLogTopic, BrokerLogConfig.getLogTopics, and BrokerLogConfig.setLogTopic
setLogTopic
void setLogTopic( String code, boolean enabled, String value) throws BrokerException
Sets the value of a single log output's state.
See BrokerLogConfigEntry on page 394 for more information.
See Also:
BrokerLogConfig.getLogTopic, BrokerLogConfig.getLogTopics, and BrokerLogConfig.setLogTopic
log_topic The log topic that is to be set.
Possible Exceptions Meaning
BrokerNullParameterException log_topic parameter is null or log_topic.code is null.
code Specifies the log topic whose state is to be set. Must be one of the following values:
LOG_TOPIC_ALERT
LOG_TOPIC_WARNING
LOG_TOPIC_INFO
enabled If set to true, this topic is enabled.
value The value to be set. Usually set to null.
Possible Exceptions Meaning
BrokerNullParameterException The code parameter is null.
webMethods Broker Administration Java API Programmer’s Guide Version 8.2 393
12 Java API Administration Reference
toString
String toString()
Returns a string containing the log configuration in a human-readable format.
toString
String toString( int indent_level)
Returns a string containing the log configuration object in a human-readable format.
BrokerLogConfigEntry
class BrokerLogConfigEntry extends java.lang.Object
This class describes the log setting for a single type of log output or log topic.
Variables
code
String code
Represents the type of log output or log topic. If the BrokerLogConfigEntry is representing the state of a particular type of log output, it must contain one of the following values:
BrokerLogConfig.LOG_OUTPUT_NT_EVENT_LOG
BrokerLogConfig.LOG_OUTPUT_SNMP_TRAP
BrokerLogConfig.LOG_OUTPUT_UNIX_SYSLOG
If the BrokerLogConfigEntry is representing the state of a particular type of log topic, it must contain one of the following values:
BrokerLogConfig.LOG_TOPIC_ALERT
BrokerLogConfig.LOG_TOPIC_INFO
BrokerLogConfig.LOG_TOPIC_WARNING
enabled
boolean enabled
Represents the state of the log output or log topic defined by code. If true, the log output or topic represented by this object is enabled. If false, it is disabled.
indent_level The number of 4-space indentations that should be generated in the output.
394 webMethods Broker Administration Java API Programmer’s Guide Version 8.2
12 Java API Administration Reference
value
String value
A string that is associated with a log topic or log output. Used with LOG_OUTPUT_UNIX_SYSLOG to store the syslog facility.
Constructors
BrokerLogConfigEntry
BrokerLogConfigEntry()
Creates an empty log configuration entry.
BrokerLogConfigEntry
BrokerLogConfigEntry( String new_code, boolean new_enabled, String new_value) throws BrokerException
Creates an initialized log entry.
BrokerMonitorClientpublic class BrokerMonitorClient extends java.lang.Object
This class represents a Broker Monitor client.
new_code Indicates the type of log output or log topic. Must be one of the following BrokerLogConfig values:
LOG_OUTPUT_UNIX_SYSLOG
LOG_OUTPUT_NT_EVENT_LOG
LOG_OUTPUT_SNMP_TRAP
LOG_TOPIC_ALERT
LOG_TOPIC_INFO
LOG_TOPIC_WARNING
new_enabled If true, indicates this log output or topic is enabled. Otherwise, it is disabled.
new_value A string that is associated with the log output or topic. Usually set to null.
webMethods Broker Administration Java API Programmer’s Guide Version 8.2 395
12 Java API Administration Reference
Constant
BROKER_MONITOR_DEFAULT_PORT
Constructors
BrokerMonitorClient
BrokerMonitorClient(String broker_monitor_host) throws BrokerException
Creates a BrokerMonitorClient object for the specified Broker Monitor host. Make sure the Broker Monitor process is running before creating the BrokerMonitorClient object.
BrokerMonitorClient
BrokerMonitorClient( String broker_monitor_host, BrokerConnectionDescriptor desc) throws BrokerException
Creates a BrokerMonitorClient object for the specified Broker Monitor host. Make sure the Broker Monitor process is running before creating the BrokerMonitorClient object.
broker_monitor_host
The Broker Monitor host for which this Broker Monitor client is being created. Specified in the form <broker_monitor_host_name>:<port_number>. If you omit the port number, the default port number specified by BROKER_MONITOR_DEFAULT_PORT will be used.
Possible Exceptions Meaning
BrokerCommFailureException A problem occurred while establishing the connection.
BrokerHostNotFoundException The specified Broker Monitor host cannot be located.
BrokerNotRunningException A Broker Monitor could not be found on the broker_monitor_host.
BrokerNullParameterException The broker_monitor_host parameter is null.
broker_monitor_host
The Broker Monitor host for which this Broker Monitor client is being created. Specified as <broker_monitor_host_name>:<port_number>. If you omit the port number, the default port number specified by BROKER_MONITOR_DEFAULT_PORT will be used.
desc The connection descriptor to use for the new BrokerMonitorClient. If null, a default connection will be established.
396 webMethods Broker Administration Java API Programmer’s Guide Version 8.2
12 Java API Administration Reference
Methods
destroy
void destroy() throws BrokerException
Destroys the Broker Monitor client. Marks the local Broker Monitor client object as disconnected and throws an exception.
getHostName
String getHostName()
Returns the host name of the Broker Monitor.
getPort
int getPort()
Returns the port number used by the Broker Monitor.
getServerLogEntries
BrokerServerLogEntry[] getServerLogEntries( int base_port, BrokerDate first_entry, String locale, int num_entries) throws BrokerException
Possible Exceptions Meaning
BrokerCommFailureException A problem occurred while establishing the connection.
BrokerHostNotFoundException The specified Broker Monitor host cannot be located.
BrokerNotRunningException A Broker Monitor could not be found on the broker_monitor_host.
BrokerNullParameterException The broker_monitor_host parameter is null.
Possible Exception Meaning
BrokerInvalidClientException The Broker Monitor client has been destroyed or disconnected.
base_port The port number of the Broker Server to which this Broker Monitor client is connected.
webMethods Broker Administration Java API Programmer’s Guide Version 8.2 397
12 Java API Administration Reference
Returns a BrokerServerLogEntry array containing the desired log entries of the Broker Server to which this Broker Monitor client is connected. You specify the date of the first entry, the locale, and the number of entries. The parameter num_entries can be set to the number of entries desired or to SERVER_LOG_ALL_ENTRIES if you wish all entries to be returned.
Note: Attempting to obtain all server log entries may create performance problems and may use up significant memory.
getServerLogStatus
BrokerServerLogInfo getServerLogStatus( int base_port) throws BrokerException
Returns the log status for the Broker Server to which this Broker Monitor client is connected. The BrokerServerLogInfo object returned contains the date and time of the first and last log entries, as well as the current number of entries in the log.
first_entry The date of the first entry desired. If null, the entries will start with the first one that appears in the Broker Server's log.
locale The locale. If set to null, the Broker Server's default locale is used.
num_entries The maximum number of log entries desired. If set to SERVER_LOG_ALL_ENTRIES, all entries in the log will be retrieved.
Possible Exceptions Meaning
BrokerIncompatibleVersionException Broker Server version does not support this operation.
BrokerInvalidClientException TheBroker Monitor client has been destroyed or disconnected.
BrokerNoPermissionException The Broker Monitor client has limited access.
BrokerOutOfRangeException The value of num_entries parameter is less than -1.
base_port The port number of the Broker Server.
Possible Exceptions Meaning
BrokerIncompatibleVersionException Broker Server version does not support this operation.
BrokerInvalidClientException The Broker Monitor client has been destroyed or disconnected.
BrokerNoPermissionException The Broker Monitor client has limited access.
398 webMethods Broker Administration Java API Programmer’s Guide Version 8.2
12 Java API Administration Reference
getServerRunStatus
int getServerRunStatus( int port) throws BrokerException
Returns the current status of the Broker Server. Returns one of the following values of the Broker Server:
SERVER_STATUS_ERROR
SERVER_STATUS_RUNNING
SERVER_STATUS_STARTING
SERVER_STATUS_STOPPED
SERVER_STATUS_STOPPING
getServers
BrokerServerInfo[] getServers() throws BrokerException
Returns the configuration details of all Broker Servers on the specified host.
getVersion
String getVersion() throws BrokerException
Returns the version of Broker Monitor.
port The port number of the Broker Server.
Possible Exceptions Meaning
BrokerInvalidClientException The Broker Monitor client has been destroyed or disconnected.
BrokerUnknownServerException No Broker Server is configured on the specified port.
Possible Exception Meaning
BrokerInvalidClientException TheBroker Monitor client has been destroyed or disconnected.
Possible Exception Meaning
BrokerInvalidClientException The Broker Monitor client has been destroyed or disconnected.
webMethods Broker Administration Java API Programmer’s Guide Version 8.2 399
12 Java API Administration Reference
getVersionNumber
int getVersionNumber()
Returns the version number of Broker Monitor. Returns the version number of Broker Monitor client if Broker Monitor is newer than the Broker Monitor client's version.
pruneMonitorLog
void pruneMonitorLog( int base_port BrokerDate older_than) throws BrokerException
Deletes entries from the Broker Monitor log. Deletes all entries that are older than or equal to the date specified by the older_than parameter.
reloadConfig
void reloadConfig() throws BrokerException
Broker Monitor reloads the configuration of all the connected Broker Servers.
reloadConfigForServer
void reloadConfigForServer( int port ) throws BrokerException
Broker Monitor reloads the configuration of the Broker Server running on port.
base_port The port number of the Broker Server.
older_than The date for deleting entries that are older than or equal to the older_than date.
Possible Exceptions Meaning
BrokerIncompatibleVersionException Broker Server version does not support this operation.
BrokerInvalidClientException The Broker Monitor client has been destroyed or disconnected.
BrokerNoPermissionException The Broker Monitor client has limited access.
BrokerNullParameterException The value of the older_than parameter is null.
port The port number of the Broker Server.
400 webMethods Broker Administration Java API Programmer’s Guide Version 8.2
12 Java API Administration Reference
startServer
void startServer( int port ) throws BrokerException
Broker Monitor client starts the Broker Server configured on the specified port.
toString
String toString()
Returns the Broker Monitor client details. Returns null if the Broker Monitor client is not valid.
BrokerProcessInfo
class BrokerProcessInfo extends java.lang.Object
This class is used to contain process information for a Broker.
Variables
data_directory
String data_directory
The directory where data for the Broker will be written.
exectuable_name
String exectuable_name
Possible Exceptions Meaning
BrokerInvalidClientException The Broker Monitor client has been destroyed or disconnected.
BrokerUnknownServerException No Broker Server is configured on the specified port.
port The port number of the Broker Server.
Possible Exceptions Meaning
BrokerInvalidClientException The Broker Monitor client has been destroyed or disconnected.
BrokerUnknownServerException No Broker Server is configured on the specified port.
webMethods Broker Administration Java API Programmer’s Guide Version 8.2 401
12 Java API Administration Reference
The name of the Broker's executable file.
Constructors
BrokerProcessInfo
BrokerProcessInfo()
Creates an uninitialized process information object.
BrokerProcessInfo
BrokerProcessInfo( String new_name, String new_directory)
Creates an initialized process information object.
BrokerQueueBrowserinterface BrokerQueueBrowser
This interface provides queue browsing capabilities to view events from both client queues and forwarding queues.
Methods
browseEvents
BrokerEvent[] browseEvents( int max_events, int msecs) throws BrokerException
Browses the queue and returns one or more events from the client queue or forwarding queue. Returns immediately with one of the following:
An array of events if found. The number of events being returned is not guaranteed to be max_events even if there are more than max_events in the queue. Any number of events up to the value of max_events may be returned.
An error if the end of queue is reached. 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.
new_name The name of the Broker's executable file.
new_directory The name of the directory where the Broker's output will be written.
402 webMethods Broker Administration Java API Programmer’s Guide Version 8.2
12 Java API Administration Reference
In addition to the listed exceptions, any communications exception can be thrown.
closeQueueBrowser
void closeQueueBrowser() throws BrokerException
Closes the current client queue or forwarding queue browser object; otherwise throws Broker exception.
getBrowserInfo
BrokerQueueBrowserInfo getBrowserInfo() throws BrokerException
Gets information about the current client queue browser. Returns a BrokerQueueBrowserInfo object.
getFilters
COM.activesw.api.client.BrokerFilterDescriptor[] getFilters() throws BrokerException
Returns the list of filters currently set on the client queue browser.
Possible Exceptions Meaning
BrokerTimeoutException The timeout is reached before an event arrives.
BrokerOutOfRangeException The max_events or msecs parameter is less than zero.
BrokerQueueBrowserException The queue browser is invalid.
BrokerQueueBrowserException The event at the last cursor position was removed. Reset the cursor to a valid position before attempting a browse operation.
BrokerQueueBrowserException The queue is busy; retry the operation later.
BrokerQueueBrowserException The queue is empty and no more events can be returned. For forwarding queues, this exception might be thrown when there are only internal events within the requested browsing range.
BrokerInvalidClientException The client has been destroyed or is disconnected.
Possible Exceptions Meaning
BrokerQueueBrowserException The queue browser is invalid.
Possible Exceptions Meaning
BrokerQueueBrowserException The queue browser is invalid.
webMethods Broker Administration Java API Programmer’s Guide Version 8.2 403
12 Java API Administration Reference
resetFilters
void resetFilters() throws BrokerException
Removes the filters set on the client queue browser. Any subsequent browse requests would consider all the events in the queue.
setFilter
void setFilter( COM.activesw.api.client.BrokerFilterDescriptor filter) throws BrokerException
Sets the filter for the client queue browser's browse operation. Any subsequent browse requests would return only those events that satisfy the filter condition. If a filter for the specified document type already exists on the queue browser, it will be overwritten with the new filter setting.
setFilters
void setFilters( COM.activesw.api.client.BrokerFilterDescriptor[] filters) throws BrokerException
Sets multiple filters for the client queue browser's browse operation. Any subsequent browse requests would return only those events that satisfy the filter conditions. If a filter for the specified document type already exists on the queue browser, it will be overwritten with the new filter settings.
Possible Exceptions Meaning
BrokerQueueBrowserException The queue browser is invalid.
Possible Exceptions Meaning
BrokerQueueBrowserException The queue browser is invalid.
BrokerFilterParseException An error occurred while parsing the filter expression
BrokerInvalidFilterException The specified filter expression on the filter object is invalid.
BrokerNullParameterException The filter parameter is null or the filter expression on the BrokerFilterDescriptor is null.
BrokerUnknownEventTypeException The specified event type on the filter object does not exist on Broker.
Possible Exceptions Meaning
BrokerQueueBrowserException The queue browser is invalid.
404 webMethods Broker Administration Java API Programmer’s Guide Version 8.2
12 Java API Administration Reference
setPosition
void setPosition( int position) throws BrokerException
Set the browser's cursor position to the specified position on the client queue or forwarding queue, where a value of '0' represents the head of the queue and a value of "queue length minus one" represents the end of the queue. Valid position values are in the range of 0 and "queue length-1".
BrokerQueueBrowserInfo
class BrokerQueueBrowserInfo extends java.lang.Object
This class holds detailed information of a queue browser.
Variables
clientId
String clientId
The ID of the client queue or forwarding queue being browsed.
browserId
String browserId
BrokerFilterParseException An error occurred while parsing the filter expression
BrokerInvalidFilterException The specified filter expression on the filter object is invalid.
BrokerNullParameterException The filters parameter is null or the filter expression on the BrokerFilterDescriptor is null.
BrokerUnknownEventTypeException The specified event type on the filter object does not exist on Broker.
Possible Exceptions Meaning
BrokerQueueBrowserException The queue browser is invalid or the specified queue position is out of bounds: the position is less than zero or the position is greater than/equal to the queue length.
Possible Exceptions Meaning
webMethods Broker Administration Java API Programmer’s Guide Version 8.2 405
12 Java API Administration Reference
Client ID of the client that is browsing the queue.
browserSessionId
int browserSessionId
Session ID of the browsing client.
locked
boolean locked
Queue locked flag
createTime
long createTime
Queue browser creation time. For BrokerLockedQueueBrowsers, this would be the lock acquisition time.
Constructors
BrokerQueueBrowserInfo
BrokerQueueBrowserInfo ()
Create an empty lock info object.
BrokerQueueBrowserInfo
BrokerQueueBrowserInfo( java.lang.String clientId, java.lang.String browserId, int browserSessionId, boolean locked, boolean acquired, int createTime)
Create and initialize a lock info object.
BrokerServerClient
class BrokerServerClient extends java.lang.Object
This class represents a Broker Server client that is used to administer system-wide setting for a particular host running one or more Brokers. It provides methods for creating and destroying a Broker as well as for configuring and querying the Broker's state.
406 webMethods Broker Administration Java API Programmer’s Guide Version 8.2
12 Java API Administration Reference
Variables
SERVER_STATUS_ERROR
SERVER_STATUS_RUNNING
SERVER_STATUS_STARTING
SERVER_STATUS_STOPPED
SERVER_STATUS_STOPPING
SSL_STATUS_DISABLED
SSL_STATUS_ENABLED
SSL_STATUS_ERROR
SSL_STATUS_NOT_SUPPORTED
Constructors
BrokerServerClient
BrokerServerClient( String broker_host, BrokerConnectionDescriptor desc) throws BrokerException
Creates a BrokerServerClient object for the specified Broker Server.
A Broker Server client is said to have limited access if it is not authorized under the host's Access Control List. Some methods offered by this class will throw a BrokerNoPermissionException if the client has limited access.
Note: The shared state flag of the BrokerConnectionDescriptor associated with this client is always ignored.
broker_host The Broker host for which this administrative client is being created. 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
desc The connection descriptor to use for the new BrokerServerClient. If null, a default connection will be established.
Possible Exceptions Meaning
BrokerCommFailureException A problem occurred establishing the connection.
BrokerHostNotFoundException The specified host cannot be located.
webMethods Broker Administration Java API Programmer’s Guide Version 8.2 407
12 Java API Administration Reference
Methods
createBroker
void createBroker( String broker_name, String description, boolean is_default) throws BrokerException
Creates a Broker with the specified broker_name on the host to which this BrokerServerClient is currently connected.
Note: For information on Broker name restrictions, see the webMethods Broker Client Java API Programmer’s Guide.
destroy
void destroy() throws BrokerException
Destroys this BrokerServerClient object, disconnecting from the Broker Server in the process. This BrokerServerClient object is marked as disconnected even if an exception is thrown.
BrokerNotRunningException A Broker could not be found on the broker_host.
BrokerNullParameterException The broker_host parameter is null.
broker_name The name of the Broker that is being created.
description A description of this Broker.
is_default If set to true, this will be the default Broker for this host.
Possible Exceptions Meaning
BrokerExistsException A Broker with the same broker_name already exists on the host.
BrokerInvalidBrokerNameException The broker_name is not valid.
BrokerInvalidClientException The BrokerServerClient has been destroyed or disconnected.
BrokerNoPermissionException Permission to create a Broker on the host was denied.
BrokerNullParameterException broker_name or description parameter is null.
Possible Exceptions Meaning
408 webMethods Broker Administration Java API Programmer’s Guide Version 8.2
12 Java API Administration Reference
See Also:
BrokerServerClient.getActivePort
getActivePort
int getActivePort() throws BrokerException
Returns the base port number currently in use by the Broker host. The base port is used for non-SSL connections and has a default value of 6849. The base port number is also used to calculate the port numbers shown in the table in BrokerAdminTypeDef on page 302.
The following table shows the port numbers calculated from the base port number.
getActiveProcessInfo
BrokerProcessInfo getActiveProcessInfo() throws BrokerException
Returns the process information currently for the Broker Server.
See BrokerProcessInfo on page 401 for information on the returned object.
getActiveSSLConfig
BrokerSSLConfig getActiveSSLConfig() throws BrokerException
Possible Exceptions Meaning
BrokerInvalidClientException The BrokerServerClient has been destroyed or disconnected.
Port number Description
base port minus 1 Used for SSL connections without client authentication.
base port minus 2 Used for SSL connections with client authentication.
Possible Exceptions Meaning
BrokerInvalidClientException The BrokerServerClient has been destroyed or disconnected.
Possible Exceptions Meaning
BrokerInvalidClientException The BrokerServerClient has been destroyed or disconnected.
BrokerNoPermissionException Client does not have permission to obtain the Broker's active port.
webMethods Broker Administration Java API Programmer’s Guide Version 8.2 409
12 Java API Administration Reference
Returns a BrokerSSLConfig object that represents the Broker Server's current SSL configuration. This may or may not be the same as the saved SSL configuration, which will take effect the next time the Broker Server is started.
Important! This method only works with Broker Server 6.5.2 version or earlier.
See Also:
BrokerServerClient.getSavedSSLConfig, BrokerServerClient.getSSLStatus, and BrokerServerClient.setSSLConfig
getActiveSSLConfigV2
BrokerSSLConfigV2 getActiveSSLConfigV2() throws BrokerException
Returns a BrokerSSLConfigV2 object that represents the Broker Server's current SSL configuration. This may or may not be the same as the saved SSL configuration, which will take effect the next time the Broker Server is started.
See Also:
BrokerServerClient.getSavedSSLConfig, BrokerServerClient.getSSLStatus, and BrokerServerClient.setSSLConfig
getActiveSSLIdentity
BrokerSSLIdentity getActiveSSLIdentity() throws BrokerException
Returns a BrokerSSLIdentity object that provides information about the Broker Server's SSL identity (DNs).
Possible Exceptions Meaning
BrokerInvalidClientException The BrokerServerClient has been destroyed or disconnected.
BrokerNoPermissionException The client does not have permission to obtain the Broker's active SSL configuration.
Possible Exceptions Meaning
BrokerInvalidClientException The BrokerServerClient has been destroyed or disconnected.
BrokerNoPermissionException The Client does not have permission to obtain the Broker's active SSL configuration.
BrokerIncompatibleVersionException If the Broker does not support the old form of SSL configuration.
410 webMethods Broker Administration Java API Programmer’s Guide Version 8.2
12 Java API Administration Reference
Important! This method only works with Broker Servers 7.1 version and higher.
getBasicAuthIdentity
public BrokerBasicAuthIdentity getBasicAuthIdentity() throws BrokerException
Returns the Broker Server's basic authentication identity that is in use.
Note: This method only works with Broker Servers version 8.2 and higher.
See Also:
BrokerServerClient.setBasicAuthIdentity
getBasicAuthStatus
public boolean getBasicAuthStatus() throws BrokerException
Returns whether basic authentication is configured on Broker Server. The possible values are "True" and "False". This operation is open to all users.
Possible Exceptions Meaning
BrokerInvalidClientException The BrokerServerClient has been destroyed or disconnected.
BrokerNoPermissionException Client does not have permission to obtain the Broker's active SSL configuration.
Possible Exception Meaning
BrokerInvalidClientException The BrokerServerClient has been destroyed or is disconnected.
BrokerNoPermissionException The client does not have permission to obtain the Broker's basic authentication identity.
BrokerIncompatibleVersionException The Broker Server does not support this operation.
Possible Exception Meaning
BrokerInvalidClientException The BrokerServerClient has been destroyed or is disconnected.
BrokerIncompatibleVersionException The Broker Server does not support this operation.
webMethods Broker Administration Java API Programmer’s Guide Version 8.2 411
12 Java API Administration Reference
Note: This method only works with Broker Servers version 8.2 and higher.
getSavedSSLidentity
BrokerSSLIdentity getSavedSSLIdentity() throws BrokerException
Returns a BrokerSSLIdentity object that provides information about the Broker Server's SSL identity (DNs).
Important! This method only works with Broker Servers 7.1 version and higher.
getAdminACL
BrokerAccessControlList getAdminACL() throws BrokerException
Returns a BrokerAccessControlList object containing the distinguished names of the entities that may perform administration operations on the Broker Server.
See Also:
BrokerServerClient.setAdminACL
getBrokers
BrokerInfo[] getBrokers() throws BrokerException
Returns an array of BrokerInfo objects representing all the Brokers available on the host to which this BrokerServerClient is connected. All administrative clients have permission to use this method.
Possible Exceptions Meaning
BrokerInvalidClientException The BrokerServerClient has been destroyed or is disconnected.
BrokerNoPermissionException The client does not have permission to obtain the Broker's active SSL configuration.
Possible Exceptions Meaning
BrokerInvalidClientException The BrokerServerClient has been destroyed or disconnected.
BrokerNoPermissionException Client does not have permission to obtain the host's Access Control List.
412 webMethods Broker Administration Java API Programmer’s Guide Version 8.2
12 Java API Administration Reference
See Also:
BrokerServerClient.getDefaultBrokerName
getDefaultBrokerName
String getDefaultBrokerName() throws BrokerException
Returns a string containing the name of the default Broker on the host to which this BrokerServerClient is connected. All administrative clients have permission to use this method.
A null string is returned if there is no default Broker.
See Also:
BrokerServerClient.getBrokers and BrokerServerClient.setDefaultBrokerName
getDescription
String getDescription() throws BrokerException
Returns a string containing a description for the Broker Server.
See Also:
BrokerServerClient.setDescription
getDNsFromCertFile
String[] getDNsFromCertFile( String certificate_file, String password) throws BrokerException
Possible Exceptions Meaning
BrokerInvalidClientException The BrokerServerClient has been destroyed or disconnected.
Possible Exceptions Meaning
BrokerInvalidClientException The BrokerServerClient has been destroyed or disconnected.
Possible Exceptions Meaning
BrokerInvalidClientException The BrokerServerClient has been destroyed or disconnected.
certificate_file The certificate file whose distinguished names are to be returned. If null, the host's active certificate file is used.
webMethods Broker Administration Java API Programmer’s Guide Version 8.2 413
12 Java API Administration Reference
Returns the distinguished names contained in the specified certificate_file on the Broker host.
If the Broker does not currently have an active SSL configuration and one or both of the parameters are null, a null parameter exception will be thrown.
Important! This field only works with version 6.5.2 or earlier Broker Servers.
See Also:
BrokerServerClient.getActiveSSLConfig, BrokerServerClient.getSavedSSLConfig, and BrokerServerClient.setSSLConfig
getFIPSMode
String getFIPSMode() throws BrokerException
Returns the version of the OpenSSL used if the FIPS mode is enabled in Broker Server. Returns null if the FIPS mode is disabled.
password The password for accessing the certificate_file. May be null if the certificate_file parameter is null or if the host's active certificate file uses the same password.
Possible Exceptions Meaning
BrokerFileNotFoundException The specified certificate_file could not be found.
BrokerInvalidClientException The BrokerServerClient has been destroyed or disconnected.
BrokerNoPermissionException The password is invalid, or certificate_file does not contain certificates, or the client does not have permission to access the SSL information.
Possible Exceptions Meaning
BrokerInvalidClientException The BrokerServerClient has been destroyed or disconnected.
BrokerIncompatibleVersionException The Broker does not support FIPS.
BrokerNoPermissionException The client does not have permission to access the FIPS information.
BrokerTimeoutException The FIPS information was not returned within the time-out interval.
414 webMethods Broker Administration Java API Programmer’s Guide Version 8.2
12 Java API Administration Reference
getHostName
Important! This field only works with version 6.5.2 or earlier Broker Servers.
String getHostName()
Returns the host name associated with this Broker host.
getLicense
String getLicense() throws BrokerException
Returns a string containing the full path to the Broker host's license file.
Note: Returns a string containing the Broker host's license for Broker Servers earlier than 8.2 version.
See Also:
BrokerServerClient.setLicense
getLicenseContent
String getLicenseContent() throws BrokerException
Returns a string containing the Broker host's license file content.
See Also:
BrokerServerClient.setLicenseContent
Possible Exceptions Meaning
BrokerInvalidClientException The BrokerServerClient has been destroyed or disconnected.
BrokerNoPermissionException The client does not have permission to access the SSL information.
Possible Exceptions Meaning
BrokerInvalidClientException The BrokerServerClient has been destroyed or disconnected.
BrokerNoPermissionException The client does not have permission to access the SSL information.
webMethods Broker Administration Java API Programmer’s Guide Version 8.2 415
12 Java API Administration Reference
getLogConfig
BrokerLogConfig getLogConfig() throws BrokerException
Returns a BrokerLogConfig object that represents the Broker Server's logging configuration. This operation is available to all users.
See Also:
BrokerServerClient.setLogConfig
getPublicationProcessingState
int getPublicationProcessingState() throws BrokerException {
Returns the publication processing state of the Broker Server. A return value of 0 indicates that event publication is active. A return value of 1 indicates that event publication is paused.
See Also:
BrokerServerClient.pruneServerLog and BrokerServerClient.resumePublishProcessing.
getRootDNsFromCertFile
String[] getRootDNsFromCertFile( String certificate_file, String password) throws BrokerException
Returns the list of trusted root distinguished names available in the certificate_file on the Broker Server.
If the password and certificate_file parameters are both null, the Broker's active certificate file and password are used.
Possible Exceptions Meaning
BrokerInvalidClientException The BrokerServerClient has been destroyed or disconnected.
Possible Exceptions Meaning
BrokerInvalidClientException The BrokerServerClient has been destroyed or disconnected.
certificate_file The certificate file whose trusted root distinguished names are to be returned.
password The password for the certificate file. May be null if certificate_file is also null.
416 webMethods Broker Administration Java API Programmer’s Guide Version 8.2
12 Java API Administration Reference
If the Broker does not currently have an active SSL configuration, then null parameter exceptions will be returned as appropriate.
Important! This field only works with version 6.5.2 or earlier Broker Servers.
getDNFromKeyStore
String getDNsFromKeystore( String keystore, String password, BrokerSSLConfigV2.KeystoreType keystoreType) throws BrokerException
Returns the distinguished name from the certificate in the specified keystore.
See BrokerSSLConfigV2 on page 447 for more information.
Important! This method only works with Broker Servers 7.1 version and higher.
See Also:
BrokerServerClient.getSSLStatus.
Possible Exceptions Meaning
BrokerFileNotFoundException The specified certificate_file could not be found or could not be read.
BrokerInvalidClientException The BrokerServerClient has been destroyed or disconnected.
BrokerNoPermissionException The password specified is not valid or certificate_file does not contain certificates.
keystore The certificate file whose distinguished name is to be returned.
password The password for the keystore file. May be null if keystore is also null.
keystoreType The keystoreType parameter specifies the type of keystore: either PKCS12 or PEM.
Possible Exceptions Meaning
BrokerInvalidClientException The BrokerServerClient has been destroyed or disconnected.
BrokerNoPermissionException The client does not have permission to access the SSL information.
webMethods Broker Administration Java API Programmer’s Guide Version 8.2 417
12 Java API Administration Reference
getIssuerDNFromKeystore
String[] getIssuerDNFromKeystore( String keystore, String password, BrokerSSLConfigV2.KeystoreType keystoreType) throws BrokerException
Returns the issuer distinguished name in the given keystore on the Broker Server.
getRootDNsFromTrustStore
String getDNsFromKeystore( String truststore, throws BrokerException
Returns the distinguished name from the trusted root certificate in the specified trust store.
See BrokerSSLConfigV2 on page 447 for more information.
Important! This method only works with Broker Servers 7.1 version and higher.
See Also:
BrokerServerClient.getSSLStatus.
getSavedSSLConfig
BrokerSSLConfig getSavedSSLConfig() throws BrokerException
Possible Exceptions Meaning
BrokerFileNotFoundException If the keystore is not found or cannot be read.
BrokerInvalidClientException The client has been destroyed.
BrokerNoPermissionException If the password is invalid or if the file is not a keystore, or if the client has limited access.
BrokerNullParameterException If keystore is null.
BrokerSSLConfigException If the keystoreType is invalid.
truststore The trusted root whose distinguished name is to be returned.
Possible Exceptions Meaning
BrokerInvalidClientException The BrokerServerClient has been destroyed or disconnected.
BrokerNoPermissionException The client does not have permission to access the SSL information.
418 webMethods Broker Administration Java API Programmer’s Guide Version 8.2
12 Java API Administration Reference
Returns the SSL configuration the Broker host will use the next time it is started. This may differ from the current SSL configuration.
See BrokerSSLConfig on page 446 for more information.
Important! This method only works with Broker Servers 7.1 version and higher.
See Also:
BrokerServerClient.getActiveSSLConfig, BrokerServerClient.getSSLStatus, and BrokerServerClient.setSSLConfig.
getSavedSSLConfigV2
BrokerSSLConfigV2 getSavedSSLConfigV2() throws BrokerException
Returns the SSL configuration the Broker host will use the next time it is started. This may differ from the current SSL configuration.
See BrokerSSLConfig on page 446 for more information.
See Also:
BrokerServerClient.getActiveSSLConfig, BrokerServerClient.getSSLStatus, and BrokerServerClient.setSSLConfig.
getSavedSSLIdentity
BrokerSSLIdentity getSavedSSLIdentity() throws BrokerException
Returns the Broker Server's SSL identity that will be used the next time the Broker Server is restarted. This may not be the same as the active identity.
Possible Exceptions Meaning
BrokerInvalidClientException The BrokerServerClient has been destroyed or disconnected.
BrokerNoPermissionException The client does not have permission to access the SSL information.
Possible Exceptions Meaning
BrokerInvalidClientException The BrokerServerClient has been destroyed or disconnected.
BrokerNoPermissionException The client does not have permission to access the SSL information.
BrokerIncompatibleVersionException If the Broker does not support the old form of SSL configuration.
webMethods Broker Administration Java API Programmer’s Guide Version 8.2 419
12 Java API Administration Reference
Important! This method only works with Broker Servers 7.1 version and higher.
getServerLogEntries
BrokerServerLogEntry[] getServerLogEntries( BrokerDate first_entry, String locale, int num_entries) throws BrokerException
Returns a BrokerServerLogEntry array containing the desired Broker Server log entries. You specify the date of the first entry, the locale you provide, and the number of entries you desire. The parameter num_entries can be set to the number of entries desired or to SERVER_LOG_ALL_ENTRIES if you wish all entries to be returned.
Note: Attempting to obtain all server log entries may create performance problems and may use up significant amounts of memory.
For more information on the log entry format, see BrokerServerLogEntry on page 439.
Possible Exceptions Meaning
BrokerInvalidClientException The BrokerServerClient has been destroyed or disconnected.
BrokerNoPermissionException The client does not have permission to access the SSL information.
BrokerIncompatibleVersionException If the Broker does not support this call.
first_entry The date of the first entry desired. If null, the entries will start with the first one that appears in the Server's log.
locale The locale. If set to null, the server's default locale is used.
num_entries The maximum number of log entries desired. If set to SERVER_LOG_ALL_ENTRIES, all entries in the log will be retrieved.
Possible Exceptions Meaning
BrokerIncompatibleVersionException The Broker Server does not support this operation.
BrokerInvalidClientException The BrokerServerClient has been destroyed or disconnected.
BrokerNoPermissionException The client does not have permission to access the SSL information.
BrokerOutOfRangeException The n parameter is less than -1.
420 webMethods Broker Administration Java API Programmer’s Guide Version 8.2
12 Java API Administration Reference
See Also:
BrokerServerClient.getServerLogStatus and BrokerServerClient.pruneServerLog
getServerLogStatus
BrokerServerLogInfo getServerLogStatus() throws BrokerException
Returns the log status for the Broker Server to which this client is connected. The BrokerServerLogInfo object that is returned contains the date and time of the first and last log entries as well as the current number of entries in the log.
See Also:
BrokerServerClient.getServerLogEntries and BrokerServerClient.pruneServerLog
getServerProcessRunStatus
static int getServerProcessRunStatus( String broker_host) throws BrokerException
Returns the state of the Broker Server process on the specified broker_host. Returns one of the following values:
SERVER_STATUS_ERROR
SERVER_STATUS_RUNNING
SERVER_STATUS_STARTING
SERVER_STATUS_STOPPED
SERVER_STATUS_STOPPING
Possible Exceptions Meaning
BrokerIncompatibleVersionException The Broker Server does not support this operation.
BrokerInvalidClientException The BrokerServerClient has been destroyed or disconnected.
BrokerNoPermissionException The client does not have permission to access the SSL information.
broker_host The name of the Broker host whose state is to be returned. 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
webMethods Broker Administration Java API Programmer’s Guide Version 8.2 421
12 Java API Administration Reference
See Also:
BrokerServerClient.startServerProcess and BrokerServerClient.stopProcess
getServerProcessRunStatus
static int getServerProcessRunStatus( String broker_monitor_host, int monitor_port, int broker_port) throws BrokerException
Returns the state of the Broker Monitor process on the specified broker_host. Returns one of the following values:
SERVER_STATUS_ERROR
SERVER_STATUS_RUNNING
SERVER_STATUS_STARTING
SERVER_STATUS_STOPPED
SERVER_STATUS_STOPPING
Possible Exceptions Meaning
BrokerHostNotFoundException The specified broker_host does not exist.
BrokerInvalidClientException The BrokerServerClient has been destroyed or disconnected.
BrokerNotRunningException A Broker could not be found on the broker_host.
BrokerNullParameterException The broker_host parameter is null.
BrokerUnknownServerException The specified broker_host has a monitor process running, but no server is specified on the port number specified.
broker_monitor_host The name of the Broker Monitor host that manages the Broker Server whose state is to be returned.
monitor_port The port number of the Broker Monitor. If you omit the port number, the default port number will be used (6850).
broker_port The name of the Broker Server whose state is to be returned. The default is localhost:6849. Use this option to specify other Broker Servers on the local machine.
Possible Exceptions Meaning
BrokerHostNotFoundException The specified broker_host does not exist.
422 webMethods Broker Administration Java API Programmer’s Guide Version 8.2
12 Java API Administration Reference
See Also:
BrokerServerClient.startServerProcess and BrokerServerClient.stopProcess
getServerVersionNumber
int getServerVersionNumber()
Returns the version number of the Broker Server that is executing the Broker to which this admin_client is connected. If the Broker Server's version number is newer than the client's version, the client's version number is returned.
See Also
BrokerServerClient.getVersion
getSSLStatus
BrokerSSLStatus getSSLStatus() throws BrokerException
Returns a BrokerSSLStatus object representing the current SSL status for the Broker host.
See Also:
BrokerServerClient.getSavedSSLConfig, BrokerServerClient.getActiveSSLConfig, and BrokerServerClient.setSSLConfig.
getStats
BrokerEvent getStats() throws BrokerException
BrokerInvalidClientException The BrokerServerClient has been destroyed or disconnected.
BrokerNotRunningException A Broker could not be found on the broker_host.
BrokerNullParameterException The broker_host parameter is null.
BrokerUnknownServerException The specified broker_host has a monitor process running, but no server is specified on the port number specified.
Possible Exceptions Meaning
BrokerInvalidClientException The BrokerServerClient has been destroyed or disconnected.
Possible Exceptions Meaning
webMethods Broker Administration Java API Programmer’s Guide Version 8.2 423
12 Java API Administration Reference
Returns a BrokerEvent containing statistics for the Brokers running on the host to which this BrokerServerClient is currently connected. Each statistic is stored as a field in the event as shown in the following table:
Field Name Type Description
createTime BrokerDate The time the server was first started.
highestNumConnections int The highest number of non-SSL connections since the server was started.
highestNumSSLConnections int The highest number of SSL connections since the server was started.
highestNumConnectionsTime BrokerDate The time when highestNumConnections was last changed.
highestNumSSLConnectionsTime BrokerDate The time when highestNumSSLConnections was last changed.
isDiskSpaceLow boolean Set to true if there is less than 1 megabyte of free disk space.
isDiskSpaceVeryLow boolean Set to true if there is less than 100 kilobytes of free disk space.
isLicenseExpiringSoon boolean Set to true if the server's license will expire within a week.
isLicenseExpired boolean Set to true if the server's license has expired.
licensedConnections int Total number of connections, SSL and non-SSL, allowed by the server's license. If -1, there is no limit.
licenseExpirationTime BrokerDate Date when the server's license will expire. If zero, it will never expire.
licensedSSLConnections int Total number of SSL connections allowed by the server's license. If -1, there is no limit.
licenseTimeRemaining int The number of seconds until the server's license expires. If zero, it will never expire.
now BrokerDate Current time on the Broker host.
numConnections int The number of non-SSL connections to this server.
numSSLConnections int The number of SSL connections to this server.
424 webMethods Broker Administration Java API Programmer’s Guide Version 8.2
12 Java API Administration Reference
See Also:
BrokerServerClient.getUsageStats
getUsageStats
BrokerEvent getUsageStats() throws BrokerException
Returns a BrokerEvent containing system resource usage statistics for the Broker Server. Each statistic is stored as a field in the event as shown in the following table:
serverStartTime BrokerDate The time the server was most recently started.
Possible Exceptions Meaning
BrokerInvalidClientException The BrokerServerClient has been destroyed or disconnected.
Field Name Type Description
guaranteedDiskFree long The number of kilobytes of free space available to the operating system on the disk partition. This should not be confused with the amount of free space currently available to the Broker system, described by guaranteedSpaceReserved.
guaranteedDiskName string The name of the guaranteed disk partition. On a Windows platform, this is usually C:.
guaranteedDiskSize long The total number of kilobytes of disk space available to the operating system on the disk partition. This should not be confused with the amount of disk space allocated to the Broker system, described by guaranteedSpaceMax.
guaranteedSpaceAllocated long The number of kilobytes of disk space currently allocated for guaranteed space.
guaranteedSpaceMax long The maximum number of kilobytes, due to operating system limits, that the Broker system can use for guaranteed storage. Disk space reservation limits may be exceeded before this limit is reached.
Field Name Type Description
webMethods Broker Administration Java API Programmer’s Guide Version 8.2 425
12 Java API Administration Reference
guaranteedSpaceReserved long The maximum guaranteed space available to Broker minus the space actually used by Broker (guaranteedSpaceMax minus guaranteedSpaceUsed). If this value is zero, the amount of guaranteed storage for the Broker system may need to be increased.
guaranteedSpaceUsed long The maximum number of kilobytes of disk space that has ever been used by the Broker system at any point in time for guaranteed space. This number acts as a "high watermark."
maxMemorySize long The number of kilobytes of space Broker sets as a limit for memory usage.
memoryUsed long The total number of kilobytes of space allocated by Broker on the heap.
now BrokerDate Current time on the Broker host.
percentageCPUUsed double Percentage of CPU used by the Broker Server. This is a cumulative value since the creation of the current Broker Server process. This value is not set for Windows platforms.
persistentDiskFree long The number of free kilobytes of persistent disk store space.
persistentDiskName string The name of the persistent disk partition.
persistentDiskSize long The maximum number of kilobytes, due to system limits, that persistent storage can consume. Disk space reservation limits may be exceeded before this limit is reached.
persistentSpaceAllocated long The number of kilobytes of disk space currently allocated for persistent space.
persistentSpaceMax long The fixed number of kilobytes of disk space reserved for persistent space. If zero, the storage will be resized as needed.
persistentSpaceUsed long The number of kilobytes of disk space being used for persistent space.
Field Name Type Description
426 webMethods Broker Administration Java API Programmer’s Guide Version 8.2
12 Java API Administration Reference
See Also:
BrokerServerClient.getStats.
getVersion
String getVersion()
Returns a string containing the Broker Server version string. Since the version string is complex, it is recommended that you use the BrokerServerClient.getServerVersionNumber method if you want to retrieve just the version number.
See:
BrokerServerClient.getServerVersionNumber.
pruneServerLog
void pruneServerLog( BrokerDate older_than) throws BrokerException
Deletes all log entries from the Broker Server to which this client is connected. All entries with a date equal to, or older than, the date specified by older_than will be deleted.
swapSpaceFree long The number of kilobytes of free swap space.
swapSpaceMax long The total number of kilobytes of swap space.
systemTimeUsed double The number of seconds of CPU system time used by the Broker Server since it was started.
userTimeUsed double The number of seconds of CPU user time used by the Broker since it was started.
Possible Exceptions Meaning
BrokerInvalidClientException The BrokerServerClient has been destroyed or disconnected.
older_than The date of the entries that are to be deleted from the log.
Possible Exceptions Meaning
BrokerIncompatibleVersionException The Broker Server does not support this operation.
Field Name Type Description
webMethods Broker Administration Java API Programmer’s Guide Version 8.2 427
12 Java API Administration Reference
See Also:
BrokerServerClient.getServerLogEntries and BrokerServerClient.getServerLogStatus
registerConnectionCallback
void registerConnectionCallback( BrokerServerConnectionCallback obj, Object client_data) throws BrokerException
Registers a connection callback object obj for this Broker Server client. The callback object's handleHostConnectionChange 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.
You may un-register a previously registered callback object by invoking this method with a null obj parameter. For more information, see BrokerServerConnectionCallback on page 438.
See Also:
BrokerServerConnectionCallback.handleHostConnectionChange
resumePublishProcessing
void resumePublishProcessing() throws BrokerException {
This methods resumes event publishing on the Broker Server.
BrokerInvalidClientException The BrokerServerClient has been destroyed or disconnected.
BrokerNoPermissionException The client does not have permission to access the SSL information.
BrokerNullParameterException The older_than parameter is null.
obj The object whose BrokerServerConnectionCallback.handleHostConnectionChange method will be invoked when this BrokerServerClient is disconnected or reconnected.
client_data Data that is to be passed to the BrokerServerConnectionCallback.handleHostConnectionChange callback method. This may be set to null.
Possible Exceptions Meaning
BrokerInvalidClientException The BrokerServerClient has been destroyed or disconnected.
Possible Exceptions Meaning
428 webMethods Broker Administration Java API Programmer’s Guide Version 8.2
12 Java API Administration Reference
To check the state of publication processing for the Broker Server, check the return value for getPublicationProcessingState.
See Also:
BrokerServerClient.getPublicationProcessingState and BrokerServerClient.pruneServerLog.
setAdminACL
void setAdminACL( BrokerAccessControlList acl) throws BrokerException
Sets the Broker Server's access control list. This list is used to determine the entities that may create a BrokerServerClient to administer this Broker Server.
See AccessControlList on page 175 for more information.
See Also:
BrokerServerClient.getAdminACL
setBasicAuthIdentity
public void setBasicAuthIdentity( BrokerBasicAuthIdentity new_identity) throws BrokerException
Sets the Broker Server's identity for basic authentication. To disable the basic authentication identity, set the basic authentication username to null.
Possible Exceptions Meaning
BrokerInvalidClientException The BrokerServerClient has been destroyed or disconnected.
acl The access control list to set for this Broker Server.
Possible Exceptions Meaning
BrokerInvalidAccessListException The acl variable does not contain a valid access control list.
BrokerInvalidClientException The BrokerServerClient has been destroyed or disconnected.
BrokerNoPermissionException The client does not have permission to set the host's Access Control List.
BrokerNullParameterException The acl parameter is null.
new_identity The authentication identity that is to be set on Broker Server.
webMethods Broker Administration Java API Programmer’s Guide Version 8.2 429
12 Java API Administration Reference
Note: This method only works with Broker Servers version 8.2 and higher.
See Also:
BrokerServerClient.getBasicAuthIdentity
setDefaultBrokerName
void setDefaultBrokerName( String broker_name) throws BrokerException
Sets the name of the default Broker for the host. The default Broker is the one to which Broker clients will be connected if they do not specify a Broker name when creating or reconnecting a Broker client.
setDescription
void setDescription( String description) throws BrokerException
Sets the description for this Broker Server.
Possible Exceptions Meaning
BrokerBasicAuthFailureException Basic authentication failed for the user.
BrokerNullParameterException The new_identity parameter is null.
BrokerIncompatibleVersionException Broker Server does not support this operation.
broker_name The name of the Broker that is to be the default Broker. If null, there will be no default Broker for this host.
Possible Exceptions Meaning
BrokerInvalidClientException The BrokerServerClient has been destroyed or disconnected.
BrokerNoPermissionException The client does not have permission to set the default Broker.
BrokerUnknownBrokerNameException The specified broker_name does not exist.
description The description to set for this Broker Server.
Possible Exceptions Meaning
BrokerInvalidClientException The BrokerServerClient has been destroyed or disconnected.
430 webMethods Broker Administration Java API Programmer’s Guide Version 8.2
12 Java API Administration Reference
See Also:
BrokerServerClient.getDescription
setLicense
void setLicense( String license) throws BrokerException
Sets the license for the host to which this BrokerServerClient is currently connected.
See Also:
BrokerServerClient.getLicense
setLicenseContent
void setLicenseContent( String licenseFileContent) throws BrokerException
Sets the license file content for the host to which this BrokerServerClient is currently connected. This is supported by webMethods Broker 8.0 and above.
BrokerNoPermissionException The client does not have permission to set the description.
BrokerNullParameterException The description parameter is null.
license The full path of the license file to be used.
Note: Type the license string for Broker Servers earlier than 8.2 version.
Possible Exceptions Meaning
BrokerInvalidClientException The BrokerServerClient has been destroyed or disconnected.
BrokerInvalidLicenseException The license is invalid.
BrokerNoPermissionException The client does not have permission to set the license.
BrokerNullParameterException The license parameter is null.
licenseFileContent The unabridged contents of the license file to be used by webMethods Broker.
Possible Exceptions Meaning
webMethods Broker Administration Java API Programmer’s Guide Version 8.2 431
12 Java API Administration Reference
See Also:
BrokerServerClient.getLicenseContent
setLicenseFile
void setLicenseContent( String licenseFile) throws BrokerException
Sets the license file for the host to which this BrokerServerClient is currently connected. This is supported by webMethods Broker 8.0 and above.
See Also:
BrokerServerClient.getLogConfig
setLogConfig
void setLogConfig( BrokerLogConfig log_config) throws BrokerException
Sets the Broker Server's logging configuration.
Possible Exceptions Meaning
BrokerInvalidClientException The BrokerServerClient has been destroyed or disconnected.
BrokerInvalidLicenseException The license is invalid.
BrokerNoPermissionException The client does not have permission to set the license.
BrokerNullParameterException The licenseFileContent parameter is null.
licenseFile The full path of the license file to be used by webMethods Broker.
Possible Exceptions Meaning
BrokerInvalidClientException The BrokerServerClient has been destroyed or disconnected.
BrokerInvalidLicenseException The license is invalid.
BrokerNoPermissionException The client does not have permission to set the license.
BrokerNullParameterException The licenseFile parameter is null.
log_config The new logging configuration to set.
432 webMethods Broker Administration Java API Programmer’s Guide Version 8.2
12 Java API Administration Reference
See BrokerLogConfig on page 387 for more information.
See Also:
BrokerServerClient.getLogConfig
setSSLConfig
void setSSLConfig( BrokerSSLConfig new_config) throws BrokerException
Sets the SSL configuration to be used by the Broker Server. The first time the SSL configuration is set for a Broker Server, it will take effect immediately. Subsequent configurations will take effect the next time the Broker Server is started. This means that the configuration set by this method may be different from the currently active SSL configuration.
To disable SSL for this Broker Server, set the certificate file contained in new_config to null.
To change a distinguished name within the same file, set the password to null and the certificate file to the same file.
For more information, see BrokerSSLConfig on page 446.
Important! This method only works with Broker Server 6.5.2 version or earlier.
Possible Exceptions Meaning
BrokerInvalidClientException The BrokerServerClient has been destroyed or disconnected.
BrokerInvalidLogConfigException One or more log configuration entries are invalid. If throw, all valid entries are still set.
BrokerNoPermissionException The client does not have permission to access the log configuration.
new_config The SSL configuration to use the next time the Broker Server is started.
Possible Exceptions Meaning
BrokerFileNotFoundException The certificate file specified by new_config cannot be found.
BrokerInvalidClientException The BrokerServerClient has been destroyed or disconnected.
webMethods Broker Administration Java API Programmer’s Guide Version 8.2 433
12 Java API Administration Reference
See Also:
BrokerServerClient.getActiveSSLConfig, BrokerServerClient.getDNsFromCertFile, BrokerServerClient.getSavedSSLConfig, and BrokerServerClient.getSSLStatus
setSSLConfig
void setSSLConfig( String certificate_file, String password, String distinguished_name) throws BrokerException
Sets the SSL configuration to be used by the Broker Server. The first time the SSL configuration is set for a Broker Server, it will take effect immediately. Subsequent configurations will take effect the next time the Broker Server is started. This means that the configuration set by this method may be different from the currently active SSL configuration.
To disable SSL for this Broker Server, set the certificate_file to null.
To change the distinguished name without changing the certificate file, you can set the password to null.
Important! This method only works with Broker Server 6.5.2 version or earlier.
BrokerNoPermissionException The parameter new_config specifies an invalid password or an invalid certificate file, or the client does not have permission to set this configuration.
BrokerNullParameterException The parameter new_config specifies a certificate file, but the distinguished name is null. Or new_config is null.
BrokerUnknownNameException The distinguished name specified by new_config does not exist in the certificate file.
certificate_file The certificate file whose distinguished names are to be used. If null, SSL will be disabled the next time this Broker Server is started.
password The password for accessing the certificate_file. May be null if the certificate_file parameter is null or if certificate file name is not to be changed.
distinguished_name The distinguished name to be used by the Broker when it authenticates itself to Broker clients.
Possible Exceptions Meaning
434 webMethods Broker Administration Java API Programmer’s Guide Version 8.2
12 Java API Administration Reference
See Also:
BrokerServerClient.getActiveSSLConfig, BrokerServerClient.getDNsFromCertFile, BrokerServerClient.getSavedSSLConfig, and BrokerServerClient.getSSLStatus
setSSLConfig
void setSSLConfig( BrokerSSLConfigV2 config) throws BrokerException
Sets the SSL configuration to be used by the Broker Server. The first time the SSL configuration is set for a Broker Server, it will take effect immediately. Subsequent configurations will take effect the next time the Broker Server is started. This means that the configuration set by this method may be different than the currently active SSL configuration.
For more information, see BrokerSSLConfigV2 on page 447.
Important! This method only works with Broker Servers 7.1 version and higher.
Possible Exceptions Meaning
BrokerFileNotFoundException The specified certificate_file could not be found.
BrokerInvalidClientException The BrokerServerClient has been destroyed or disconnected.
BrokerNoPermissionException The password is invalid, or certificate_file does not contain certificates, or the client does not have permission to modify the SSL information.
BrokerNullParameterException The distinguished_name parameter is null, but the certificate_file is not null.
config The SSL configuration to use the next time the Broker Server is started.
Possible Exceptions Meaning
BrokerFileNotFoundException The keystore file specified by config cannot be found.
BrokerInvalidClientException The BrokerServerClient has been destroyed or disconnected.
BrokerNoPermissionException The parameter config specifies an invalid password or an invalid certificate file, or the client does not have permission to set this configuration.
BrokerNullParameterException The parameter config specifies a keystore file, but the distinguished name is null. Or config is null.
webMethods Broker Administration Java API Programmer’s Guide Version 8.2 435
12 Java API Administration Reference
startServerProcess
void startServerProcess( String broker_host) throws BrokerException
Starts the Broker Server process on the specified host if it is not already started.
See Also:
BrokerServerClient.getServerProcessRunStatus and BrokerServerClient.stopProcess
startServerProcess
void startServerProcess( String broker_monitor_host int monitor_port int broker_port) throws BrokerException
BrokerUnknownNameException The distinguished name specified by config does not exist in the keystore file.
broker_host The name of the host where the Broker host process is to be started. Specified in the form <broker_host_name>:<port_number>. If you omit the port number, the default port number will be used.
Possible Exceptions Meaning
BrokerHostNotFoundException The specified broker_host does not exist.
BrokerInvalidClientException The BrokerServerClient has been destroyed or disconnected.
BrokerNoPermissionException The client does not have permission to start Broker host process.
BrokerNotRunningException A Broker Server could not be found on the broker_host.
BrokerNullParameterException The broker_host parameter is null.
BrokerSecurityException The client is now in limited access mode because its distinguished name was not found in the Broker host's Access Control List.
broker_monitor_host The name of the Broker Monitor host that monitors the Broker Server whose process is to be started. Specified in the form <broker_host_name>:<port_number>. If you omit the port number, the default port number will be used.
Possible Exceptions Meaning
436 webMethods Broker Administration Java API Programmer’s Guide Version 8.2
12 Java API Administration Reference
Starts the Broker Server process on the specified host if it is not already started.
See Also:
BrokerServerClient.getServerProcessRunStatus and BrokerServerClient.stopProcess
stopProcess
void stopProcess() throws BrokerException
Stops the Broker Server process, if it has not already been stopped, and destroys this Broker Server client.
See Also:
BrokerServerClient.getServerProcessRunStatus and BrokerServerClient.startServerProcess
monitor_port The port number of the Broker Monitor. If you omit the port number, the default port number will be used (6850).
broker_port The port number of the Broker Server whose state is to be returned. The default is localhost:6849. Use this option to specify other Broker Servers on the local machine.
Possible Exceptions Meaning
BrokerHostNotFoundException The specified broker_host does not exist.
BrokerInvalidClientException The BrokerServerClient has been destroyed or disconnected.
BrokerNoPermissionException The client does not have permission to start Broker host process.
BrokerNotRunningException A Broker Server could not be found on the broker_host.
BrokerNullParameterException The broker_host parameter is null.
BrokerSecurityException The client is now in limited access mode because its distinguished name was not found in the Broker host's Access Control List.
Possible Exceptions Meaning
BrokerInvalidClientException The BrokerServerClient has been destroyed or disconnected.
BrokerNoPermissionException The client does not have permission to stop the Broker host process.
webMethods Broker Administration Java API Programmer’s Guide Version 8.2 437
12 Java API Administration Reference
toString
String toString()
Returns a string containing the BrokerServerClient information in a human-readable format.
BrokerServerConnectionCallback
interface BrokerConnectionCallback
You use this interface to implement an object for handling connection notification for a Broker Server client. You provide an implementation for the handleHostConnectionChange method, which will be invoked when the Broker Server client is disconnected or reconnected from its Broker Server.
You register a BrokerServerConnectionCallback-derived object using the BrokerServerClient.registerConnectionCallback method.
Methods
handleHostConnectionChange
void handleHostConnectionChange( BrokerServerClient client, int connect_state, Object client_data);
You provide an implementation of this callback method to handle host client connection notification. You can implement this method to recreate any needed client state that may 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 BrokerClient variables as shown in the following table:
client The Broker Server client whose connection state has changed.
connect_state The client's connection state. This will be set to one of the values shown in the table below.
client_data Any data that your callback method needs to perform its processing. This data is defined when you register your BrokerServerConnectionCallback object.
connect_state Meaning
CONNECT_STATE_DISCONNECTED The BrokerServerClient has been disconnected.
CONNECT_STATE_CONNECTED The BrokerServerClient connection has been re-established, because automatic reconnect was enabled.
438 webMethods Broker Administration Java API Programmer’s Guide Version 8.2
12 Java API Administration Reference
See Also:
BrokerServerClient.registerConnectionCallback
BrokerServerLogEntry
class BrokerServerLogEntry
This class is used to represent an entry in a Broker Server's log.
Constants
SERVER_LOG_MESSAGE_ALERT
SERVER_LOG_MESSAGE_INFO
SERVER_LOG_MESSAGE_UNKNOWN
SERVER_LOG_MESSAGE_WARNING
Variables
entry_msg_id
short entry_msg_id
The log entry's identifier.
entry_msg_text
String entry_msg_text
The log entry's text.
entry_type
short entry_type
The log entry's type, which should be one of the SERVER_LOG_* values described above.
CONNECT_STATE_RECONNECTED The BrokerServerClient was disconnected, but the connection was re-established immediately. This only happens if the automatic reconnect is enabled and the connection was re-established before a disconnected state could be reported.
connect_state Meaning
webMethods Broker Administration Java API Programmer’s Guide Version 8.2 439
12 Java API Administration Reference
time_stamp
BrokerDate time_stamp
The date and time the log entry was created.
Methods
toString
String toString()
Returns a string containing the Broker log entry in a human-readable format.
BrokerServerLogInfo
class BrokerServerLogInfo
This class is used to describe information about a Broker Server's log.
Variables
first_entry
BrokerDate first_entry
The date and time of the first entry in the log.
last_entry
BrokerDate last_entry
The date and time of the last entry in the log.
num_entries
int num_entries
The number of entries in the log.
BrokerSetFailureInfo
class BrokerSetFailureInfo extends java.lang.Object
This class is used to report failures from the BrokerAdminClient.setEventTypesAndClientGroups method.
440 webMethods Broker Administration Java API Programmer’s Guide Version 8.2
12 Java API Administration Reference
Variables
client_group_names_to_destroy
String client_group_names_to_destroy[]
The list of client groups which could not be destroyed.
client_group_names_to_modify
String client_group_names_to_modify[]
The list of client groups which could not be modified.
event_type_names_to_destroy
String event_type_names_to_destroy[]
The list of event types which could not be destroyed.
event_type_names_to_modify
String event_type_names_to_modify[]
The list of event types which could not be modified.
failure_type
int failure_type
The reason for the failure, one of the following values:
FAILURE_TYPE_BROKER
FAILURE_TYPE_DEPENDENCY
FAILURE_TYPE_BROKER
Constructor
BrokerSetFailureInfo
BrokerFailureInfo()
Creates an empty failure information object.
BrokerSharedEventTypeInfo
class BrokerSharedEventTypeInfo extends java.lang.Object
webMethods Broker Administration Java API Programmer’s Guide Version 8.2 441
12 Java API Administration Reference
This class stores information about how an event type is shared across a territory gateway.
Variables
accept_publish
boolean accept_publish
Set to true if the this territory accepts having events being published or delivered from the remote territory.
accept_subscribe
boolean accept_subscribe
Set to true if this territory can forward subscriptions or deliver events to the remote territory.
event_type_name
String event_type_name
The name of the event type.
is_synchronized
boolean is_synchronized
If set to true, the event type is synchronized with the remote territory. If false, the value of accept_publish and accept_subscribe are ignored since the event type will not flow between territories.
subscribe_filter
String subscribe_filter
Specifies a filter that controls which events of this type will be forwarded to other territories. If set to null, no filtering of events of this type will occur. For more information on subscription filters, see the webMethods Broker Client Java API Programmer’s Guide.
Constructors
BrokerSharedEventTypeInfo
BrokerSharedEventTypeInfo()
Creates an empty BrokerShareEventTypeInfo object.
442 webMethods Broker Administration Java API Programmer’s Guide Version 8.2
12 Java API Administration Reference
BrokerSharedEventTypeInfo
BrokerSharedEventTypeInfo( String event_type, boolean accept_pub, boolean accept_sub)
Creates and initializes a BrokerShareEventTypeInfo object.
Methods
toString
String toString()
Returns a string containing the Broker shared event type information in a human-readable format.
BrokerSharedEventTypeRefuseUpdateInfo
class BrokerSharedEventTypeRefuseUpdateInfo extends java.lang.Object
This class stores configuration information about how an event type is shared across a territory gateway. The class is used by BrokerAdminClient.setTerritoryGatewayRefuseEventTypeUpdates to obtain the event type for which the territory gateway will refuse updates.
Constructor
BrokerSharedEventTypeRefuseUpdateInfo
BrokerSharedEventTypeRefuseUpdateInfo( String event_type_name, boolean refuse_events, boolean refuse_updates) throws BrokerException
event_type The name of the event type to be shared.
accept_pub If set to true, this territory accepts event that are publish or delivered from a remote territory.
accept_sub If set to true, this territory can forward subscriptions or deliver events to the remote territory.
event_type_name The name of the event type.
webMethods Broker Administration Java API Programmer’s Guide Version 8.2 443
12 Java API Administration Reference
See Also:
BrokerAdminClient.setTerritoryGatewayRefuseEventTypeUpdates, BrokerAdminClient.getTerritoryGatewayRefuseEventTypeUpdates, BrokerAdminClient.setTerritoryGatewayRefuseAllUpdates, and BrokerAdminClient.getTerritoryGatewayRefuseAllUpdates
BrokerSSLCertificate
class BrokerSSLCertificate extends java.lang.Object
This class describes a Broker's SSL certificate, including the dates during which it is valid, the distinguished name, the distinguished name that issued it's certificate, and the serial number.
Variables
begin_date
BrokerDate begin_date
The date when the certificate first became valid.
distinguished_name
String distinguished_name
The distinguished name associated with this certificate.
end_date
BrokerDate end_date
refuse_events Whether or not this territory currently refuses events of the specified event type. If set to true, the territory will refuse events of the specified type; if set to false, the territory will not refuse those events.
refuse_updates Whether or not this territory refuses updates to the specified event type. If set to true, the territory will refuse updates to the specified event type; if set to false, the territory will not refuse the updates.
Possible Exceptions Meaning
BrokerNullParameterException The event_type_name, refuse_events, or refuse_updates parameter is null.
444 webMethods Broker Administration Java API Programmer’s Guide Version 8.2
12 Java API Administration Reference
The date when the certificate will expire.
issuer_distinguished_name
String issuer_distinguished_name
The distinguished name of the certificate authority that issued this certificate.
serial_number
String serial_number
The certificate's serial number.
status
String status
The certificate's status.
Constructors
BrokerSSLCertificate
BrokerSSLCertificate()
Creates an empty certificate object.
BrokerSSLCertificate
BrokerSSLCertificate( String new_distinguished_name, String new_issuer_distinguished_name, String new_status, String new_serial_number BrokerDate new_begin_date BrokerDate new_end_date)
Creates a certificate object with the specified attributes.
new_distinguished_name The distinguished name for the certificate.
new_issuer_distinguished_name
The distinguished name of the authority that issued the certificate.
new_status The certificate's status.
new_serial_number The certificate's serial number.
new_begin_date The date when the certificate becomes valid.
new_end_date The date when the certificate expires.
webMethods Broker Administration Java API Programmer’s Guide Version 8.2 445
12 Java API Administration Reference
BrokerSSLConfig
class BrokerSSLConfig extends java.lang.Object
This class describes a Broker's SSL configuration, including its keystore file, distinguished name, and the distinguished name of the certificate issuer.
Important! This class only works with version 6.5.2 and earlier Broker Servers. For version 7.1 Broker Servers, see BrokerSSLConfigV2 on page 447.
Variables
certificate_file
String certificate_file
The name of the certificate file for this Broker Server.
distinguished_name
String distinguished_name
The distinguished name the Broker Server will use to authenticate itself with Broker clients.
issuer_distinguished_name
String issuer_distinguished_name
The distinguished name of the certificate authority that issued this Broker Server's certificate.
password
String password
The certificate file's password. If this configuration was retrieved from a Broker, the password will be null so that it is not compromised.
Constructors
BrokerSSLConfig
BrokerSSLConfig()
Creates an empty SSL configuration object.
446 webMethods Broker Administration Java API Programmer’s Guide Version 8.2
12 Java API Administration Reference
BrokerSSLConfig
BrokerSSLConfig( String cert_file, String password, String dist_name, String issuer_dist_name)
Creates an SSL configuration object with the specified certificate file, certificate file password, distinguished name, and issuer distinguished name.
BrokerSSLConfigV2
class BrokerSSLConfigV2 extends java.lang.Object
This class describes a Broker's SSL configuration, including its CRL, keystore file, truststore file, SSL protocols that can be used, cipher suites, and maximum number of certificates in a certificate chain.
Variables
CRLType
enum CRLType { PEM, DER }
KeystoreType
enum KeystoreType { PEM, PKCS12 }
TruststoreType
enum TruststoreType { PEM, DIR }
SSLProtocol
enum SSLProtocol { TLSv1, SSLv3, ALL }
cert_file The name of the certificate file to use.
password The certificate file's password.
dist_name The distinguished name the Broker Server will use when authenticating itself with Broker clients.
issuer_dist_name The distinguished name of the certificate authority that issued the Broker Server's certificate.
webMethods Broker Administration Java API Programmer’s Guide Version 8.2 447
12 Java API Administration Reference
Constructors
BrokerSSLConfigV2
BrokerSSLConfigV2()
Creates an empty SSL configuration object.
BrokerSSLConfigV2
BrokerSSLConfigV2(BrokerSSLConfigV2)
Creates a copy of the specified SSL configuration.
Methods
getCipherSuites
String getCipherSuites()
Returns a string in OpenSSL cipher format that specifies the current encryption cipher suites.
setCipherSuites
void setCipherSuites(String newCipher_Suites)
Passes a string in OpenSSL cipher format that sets the allowable encryption cipher suites.
getCRL
String getCRL()
Returns a string containing the path to the SSL CRL file used by the SSL configuration.
setCRL
void setCRL(String crl)
Sets the full path to the SSL CRL file used by the SSL configuration on Broker Server.
getCRLType
BrokerSSLConfigV2.CRLType getCRLType()
Returns a BrokerSSLConfigV2. CRLType object containing the type of the SSL CRL file used by the SSL configuration.
crl The full path to the SSL CRL file used by the SSL configuration on Broker Server.
448 webMethods Broker Administration Java API Programmer’s Guide Version 8.2
12 Java API Administration Reference
setCRLType
void setCRLType( String crlType) throws BrokerSSLConfigException
Sets the type of the SSL CRL file to be used by the SSL configuration. Throws BrokerSSLConfigException if the value of crlType is not valid.
getKeystore
String getKeystore()
Returns a string containing the file name of the keystore.
setKeystore
void setKeystore(String newKeystore)
Sets the SSL keystore to be used by the SSL configuration.
getKeystorePassword
String getKeystorePassword()
Returns a string containing the keystore password.
setKeystorePassword
void setKeystorePassword(String newPassword)
Sets the keystore password to be used by the SSL configuration.
getKeystoreType
BrokerSSLConfigV2.KeystoreType getKeystoreType()
Returns the type of the keystore file.
setKeystoreType
void setKeystoreType(String newKeystoreType) throws BrokerSSLConfigException
crlType The type of the SSL CRL file. The type must be either PEM or DER. The default value of crlType is PEM.
newKeystoreType The type of the keystore file . The type must be KEYSTORE_TYPE_PKCS12, KEYSTORE_TYPE_PEM, or null. If the type is null, then the default keystore type, KEYSTORE_TYPE_PKCS12, is used.
webMethods Broker Administration Java API Programmer’s Guide Version 8.2 449
12 Java API Administration Reference
Sets the type of the keystore file. Throws BrokerSSLConfigException if the value of newKeystoreType is not valid.
getSslProtocol
BrokerSSLConfigV2.SSLProtocol getSslProtocol()
Returns a string containing the SSL protocols allowed for the configuration.
setSslProtocol
void setSslProtocol(String newSslProtocol)
Sets the SSL protocol to be used by the configuration.
getTruststore
String getTruststore()
Returns the string containing the name of the SSL truststore file used by the SSL configuration.
setTruststore
void setTruststore(String newTruststore)
Sets the SSL truststore file to be used by the SSL configuration.
getTruststoreType
BrokerSSLConfigV2.TruststoreType getTruststoreType()
Returns the type of the truststore file used by the SSL configuration.
newSslProtocol The SSL protocol to be used. The valid values are:
SSL_PROTOCOL_ALL
SSL_PROTOCOL_SSLV3
SSL_PROTOCOL_TLSV1
null
If the value of newSslProtocol is null, then the default SSL protocol type, SSL_PROTOCOL_ALL is used.
When you specify SSL_PROTOCOL_ALL, the SSLv3 and TLSv1 protocols are allowed, but does not allow SSLv2 or earlier versions.
newTruststore The full path to the truststore file on the machine where the Broker Server is running.
450 webMethods Broker Administration Java API Programmer’s Guide Version 8.2
12 Java API Administration Reference
setTruststoreType
void setTruststoreType(BrokerSSLConfigV2.TruststoreType newTruststoreType)
Sets the type of the truststore file to be used by the SSL configuration.
setTruststoreType
void setTruststoreType(String newTruststoreType) throws BrokerSSLConfigException
Sets the type of the truststore file to be used by the SSL configuration. Throws BrokerSSLConfigException if the value of newTruststoreType is not valid.
getVerifyDepth
int getVerifyDepth()
Returns an integer that specifies the maximum number of CA certificates allowed in a verification chain. If the certificate chain exceeds this number, then the connection is rejected.
setVerifyDepth
int setVerifyDepth(int newVerifyDepth) throws BrokerSSLConfigException
Sets the maximum number of CA certificates to be allowed in the verification chain. The default value is 9. Throws BrokerSSLConfigException if the value of newVerifyDepth is less than zero.
toString
String toString(int indent_level)
Returns the Broker's SSL configuration in a string format. The value of indent_level specifies the number of 4-space indents for the generated output.
BrokerSSLIdentity
class BrokerSSLIdentity extends java.lang.Object
newTruststoreType The BrokerSSLConfigV2.TruststoreType object to specify the type of the truststore file.
newTruststoreType The type of the truststore file . The type must be TRUSTSTORE_TYPE_PEM, TRUSTSTORE_TYPE_DIR, or null. If the type is null, then the default keystore type, TRUSTSTORE_TYPE_PEM is used.
webMethods Broker Administration Java API Programmer’s Guide Version 8.2 451
12 Java API Administration Reference
This class provides SSL identity information about a Broker Server, including the Broker Server's DN and the issuer DN for its SSL certificate.
Methods
getDN
String toString()
Returns the Broker Server's SSL DN.
getIssuerDN
String toString()
Returns the DN for the issuer of the Broker Server's SSL certificate.
BrokerSSLStatus
class BrokerSSLStatus extends java.lang.Object
This class represents a Broker's SSL status. This includes whether or not SSL is supported, configured, or enabled as well as the type of SSL that is supported.
Variables
error_string
String error_string
Describes the nature of an SSL configuration error.
level
int level
Represents the type of SSL that is supported, if status is enabled. Must be one of the following values.
BrokerServerClient.SSL_LEVEL_US_DOMESTIC
BrokerServerClient.SSL_LEVEL_US_EXPORT
status
int status
Represents the SSL status for the Broker. Must be one of the following values.
BrokerServerClient.SSL_STATUS_DISABLED
452 webMethods Broker Administration Java API Programmer’s Guide Version 8.2
12 Java API Administration Reference
BrokerServerClient.SSL_STATUS_ENABLED
BrokerServerClient.SSL_STATUS_ERROR
BrokerServerClient.SSL_STATUS_NOT_SUPPORTED
Constructors
BrokerSSLStatus
BrokerSSLStatus()
Creates an empty SSL status object.
BrokerSSLStatus
BrokerSSLStatus( int new_status, int new_level, String new_error_string)
Creates an SSL status object with the specified parameters.
BrokerTerritoryGatewayInfo
class BrokerTerritoryGatewayInfo extends java.lang.Object
This class is used to store configuration about a territory gateway. A gateway connects two distinct territories so that Broker clients in one territory can subscribe to and publish events to clients in the other territory. The gateway consists of two Brokers, each representing a distinct territory.
See “Managing Broker Territories” on page 93 for more information on territories.
new_status The status of SSL use for this Broker. Must be one of the following BrokerServerClient-defined values:
SSL_STATUS_DISABLED
SSL_STATUS_ENABLED
SSL_STATUS_ERROR
SSL_STATUS_NOT_SUPPORTED
new_level The level of SSL supported by the Broker. Must be one of the following BrokerServerClient-defined values:
SSL_LEVEL_US_DOMESTIC
SSL_LEVEL_US_EXPORT
new_error_string String describing the nature of an SSL configuration error.
webMethods Broker Administration Java API Programmer’s Guide Version 8.2 453
12 Java API Administration Reference
Variables
accessible_territories
String accessible_territories[]
The list of territories that are accessible through this gateway.
auth_type
int auth_type
The type of authentication used by the gateway. For information about the BrokerAdminClient.AUTH_TYPE_* values for this variable, see “Constants” on page 180.
encrypt_level
int encrpyt_level
The level of encryption required by the gateway. Valid values are BrokerConnectionDescriptor.ENCRYPT_LEVEL_* values are described in the webMethods Broker Client Java API Programmer’s Guide.
gateway_broker_name
String gateway_broker_name
The name of the Broker that is the gateway for this territory.
gateway_host_name
String gateway_host_name
The host on which the gateway Broker is running.
is_complete
boolean is_complete
If true, the BrokerAdminClient.createTerritoryGateway method has been invoked on each of the two Brokers that make up the gateway. If false, only one Broker has invoked the createTerritoryGateway method and the gateway is not yet complete.
is_local
boolean is_local
If true, the gateway is on the current Broker. If false, the gateway is on another Broker.
is_primary_gateway
boolean is_primary_gateway
454 webMethods Broker Administration Java API Programmer’s Guide Version 8.2
12 Java API Administration Reference
If true, the primary gateway is on the current Broker. If false, the primary gateway is on another Broker.
remote_broker_description
String remote_broker_description
The description of the remote Broker that is acting as the other end of the gateway.
remote_broker_name
String remote_broker_name
The name of the remote Broker that is acting as the other end of the gateway.
remote_host_name
String remote_host_name
The host name that is running the remote Broker.
remote_territory_name
String remote_territory_name
The name of the territory that the remote Broker is presenting to the gateway.
Methods
toString
String toString()
Returns a string containing the territory gateway information.
toString
String toString( int indent_level, boolean hide_gateway_broker, boolean hide_accessible_territories)
Returns a string containing the territory gateway information.
indent_level The number of 4-character spaces to use for indentation.
hide_gateway_broker If set to true, the gateway Broker's host and name as well as the is_local information, will be omitted.
hide_accessible_territories If set to true, the accessible_territories and is_complete information will be omitted.
webMethods Broker Administration Java API Programmer’s Guide Version 8.2 455
12 Java API Administration Reference
BrokerTerritoryInfo
class BrokerTerritoryInfo extends java.lang.Object
This class is used to store configuration about a group of Brokers that make up a territory.
See “Managing Broker Territories” on page 93 for more information on territories.
Variables
auth_type
int auth_type
The type of authentication used by the territory. To see the BrokerAdminClient.AUTH_TYPE_* values for this variable, see “Constants” on page 180.
encrypt_level
int encrpyt_level
The level of encryption required by the gateway. Valid values are BrokerConnectionDescriptor.ENCRYPT_LEVEL_* values are described in the webMethods Broker Client Java API Programmer’s Guide.
isLocalPublish
boolean isLocalPublish
Specifies whether document forwarding is enabled or disabled in the territory.
territory_name
String territory_name
The name of the territory.
Constructor
BrokerTerritoryInfo
BrokerTerritoryInfo()
Creates an empty territory information object.
456 webMethods Broker Administration Java API Programmer’s Guide Version 8.2
12 Java API Administration Reference
Methods
toString
String toString()
Returns a string containing the territory information.
toString
String toString( int indent_level)
Returns a string containing the territory gateway information.
BrokerTraceEvent
class BrokerTraceEvent extends java.lang.Object
This class represents an entry in a Broker's trace log. A trace event is created for a variety of reasons, such as the creation of a Broker client; the addition of a Broker to a territory; or when an event is published, delivered, enqueued, or received.
Each trace event has a sequence number that indicates its position in the trace log and a key that specifies the type of event being represented.
Constants
The following table shows the constants that identify the contents of a trace entry.
indent_level The number of 4-character spaces to use for indentation.
Key Event description
TRACE_BROKER_ADDED A Broker is being added to a territory.
TRACE_BROKER_REMOVED A Broker is being removed from a territory.
TRACE_CLIENT_CONNECT A Broker client is being connected.
TRACE_CLIENT_CREATE A Broker client is being created.
TRACE_CLIENT_DESTROY A Broker client is being disconnected.
TRACE_CLIENT_DISCONNECT A Broker client is being destroyed.
TRACE_CLIENT_LOCK A Broker client queue is being locked.
TRACE_CLIENT_UNLOCK A Broker client queue is being unlocked.
webMethods Broker Administration Java API Programmer’s Guide Version 8.2 457
12 Java API Administration Reference
Variables
app_name
String app_name
The name of the client application associated with the trace event. Only set for TRACE_CLIENT_CREATE and TRACE_CLIENT_DESTROY trace events. Set to null for all other trace events.
broker_host
String broker_host
For TRACE_BROKER_ADDED and TRACE_BROKER_REMOVED trace events, contains the name of the Broker Server being added to or removed from the territory.
For TRACE_EVENT_PUBLISH events, contains the name of the Broker Server that forwarded the event. Set to null if the event was not forwarded for any Broker.
For TRACE_EVENT_ENQUEUE, TRACE_EVENT_RECEIVE, and TRACE_EVENT_DROP events, contains the name of the Broker Server that enqueued, received, or dropped the event.
Set to null for all other events.
broker_name
String broker_name
For TRACE_BROKER_ADDED and TRACE_BROKER_REMOVED trace events, contains the name of the Broker being added to or removed from the territory.
TRACE_EVENT_DROP An event was dropped because a Broker client lacked the necessary permissions to receive the event. This may occur when client group permissions are changed.
TRACE_EVENT_ENQUEUE An event has been added to a Broker client's event queue by an administrative Broker Client.
TRACE_EVENT_DELETE An event has been deleted from a Broker client's queue by an administrative Broker Client.
TRACE_EVENT_INSERT An event has been inserted into a Broker client's queue.
TRACE_EVENT_PEEK An event has been peeked from a Broker client's queue.
TRACE_EVENT_PUBLISH An event has been published by a Broker client.
TRACE_EVENT_RECEIVE A Broker client has retrieved an event from its event queue.
TRACE_OTHER All other trace events.
Key Event description
458 webMethods Broker Administration Java API Programmer’s Guide Version 8.2
12 Java API Administration Reference
For TRACE_EVENT_PUBLISH events, contains the name of the Broker that forwarded the event. Set to null if the event was not forwarded.
For TRACE_EVENT_ENQUEUE, TRACE_EVENT_RECEIVE, and TRACE_EVENT_DROP events, contains the name of the Broker that enqueued, received, or dropped the event.
Set to null for all other events.
client_group
String client_group
The name of the client group associated with the trace event. Only set for TRACE_CLIENT_CREATE and TRACE_CLIENT_DESTROY trace event. Set to null for all other trace events.
client_id
String client_id
For TRACE_CLIENT_CONNECT, TRACE_CLIENT_CREATE, TRACE_CLIENT_DESTROY, and TRACE_CLIENT_DISCONNECT events, this contains the identifier of the Broker client being created or destroyed.
For TRACE_EVENT_DROP, TRACE_EVENT_ENQUEUE, TRACE_EVENT_PUBLISH, and TRACE_EVENT_RECEIVE events, it contains the identifier of the client that published or received the Broker event.
dest_client_id
String dest_client_id
For TRACE_EVENT_DROP, TRACE_EVENT_ENQUEUE, TRACE_EVENT_PUBLISH, and TRACE_EVENT_RECEIVE events, this contains the identifier of the Broker client that is the recipient of a delivered event. Set to null if this trace event is associated with an event that is not being delivered.
encrypt_level
int encrypt_level
Set to one of the BrokerConnectionDescriptor.ENCRYPT_LEVEL_* values (see the webMethods Broker Client Java API Programmer’s Guide) which describes the encryption level of the client's connection. Only set for TRACE_CLIENT_CONNECT and TRACE_CLIENT_DISCONNECT trace events.
Set to null for all other trace events.
event_id
long event_id
webMethods Broker Administration Java API Programmer’s Guide Version 8.2 459
12 Java API Administration Reference
The 64-bit identifier for the event. Only set for TRACE_EVENT_DROP, TRACE_EVENT_ENQUEUE, TRACE_EVENT_PUBLISH, and TRACE_EVENT_RECEIVE trace events.
Set to null for all other trace events.
event_type_name
String event_type_name
The name of the event type associated with the event. Only set for TRACE_EVENT_DROP, TRACE_EVENT_ENQUEUE, TRACE_EVENT_PUBLISH, and TRACE_EVENT_RECEIVE trace events.
Set to null for all other trace events.
has_tag
boolean has_tag
For TRACE_EVENT_DROP, TRACE_EVENT_ENQUEUE, TRACE_EVENT_PUBLISH, and TRACE_EVENT_RECEIVE events, set to true if the Broker event associated with this trace event has a tag field. Otherwise, set to false.
ip_address
int ip_address
The IP address of the client's host for TRACE_CLIENT_CONNECT and TRACE_CLIENT_DISCONNECT traces. This is set to zero for all other trace events.
is_authenticated
boolean is_authenticated
Set to true if the client is authenticated with the Broker.
key
int key
Identifies the type of trace entry. Is one of the constants described in “Constants” on page 457.
other_string
String other_string
Contains the trace event in its raw format. Set only when the key is set to TRACE_EVENT_OTHER.
recv_client_id
String recv_client_id
460 webMethods Broker Administration Java API Programmer’s Guide Version 8.2
12 Java API Administration Reference
The identifier of the Broker client that is the recipient of the event. Set only for TRACE_EVENT_ENQUEUE, TRACE_EVENT_RECEIVE, and TRACE_EVENT_DROP trace events.
seqn
int seqn
The trace event's sequence number. Sequence numbers begin at one and are incremented by 1.
session_count
int session_count
The number of open sessions for TRACE_CLIENT_CONNECT and TRACE_CLIENT_DISCONNECT traces.
session_id
int session_id
The client session ID for TRACE_CLIENT_CONNECT and TRACE_CLIENT_DISCONNECT traces. This represents the receiving client session ID for TRACE_EVENT_ENQUEUE, TRACE_EVENT_RECEIVE, and TRACE_EVENT_DROP trace events. This is set to zero if the client is not a shared-state client
tag
int tag
For TRACE_EVENT_DROP, TRACE_EVENT_ENQUEUE, TRACE_EVENT_PUBLISH, and TRACE_EVENT_RECEIVE events, contains the _env.tag field for the event. This is valid only if has_tag is true.
track_id
int track_id
The tracking identifier from the event's envelope. This field may be set for TRACE_EVENT_PUBLISH, TRACE_EVENT_ENQUEUE, TRACE_EVENT_RECEIVE, and TRACE_EVENT_DROP trace events. It is set to zero for all other trace events.
Constructor
BrokerTraceEvent
BrokerTraceEvent()
Creates an empty trace event.
webMethods Broker Administration Java API Programmer’s Guide Version 8.2 461
12 Java API Administration Reference
Methods
toString
String toString()
Returns a string containing the trace event in a human-readable format.
462 webMethods Broker Administration Java API Programmer’s Guide Version 8.2
A API Exceptions
This appendix describes the exceptions that are unique to the webMethods Broker Java administrative API. Other possible exceptions are described in the webMethods Broker Client Java API Programmer’s Guide.
BrokerDependencyExceptionYour request to destroy a client group or an event type (without the force--destroy option) could not be completed because there are Broker clients that depend on the group or event type.
BrokerExistsExceptionYou have attempted to create a Broker with a name that is already being used by another Broker on the same Broker Server.
BrokerInClusterExceptionYou have attempted to destroy a Broker that is currently part of a cluster or you have attempted to add a Broker to a cluster when it is already a member of a cluster.
BrokerIncompatibleVersionExceptionYou have attempted to perform an operation on a Broker Server that is not supported. This results from the Broker Server in question having an earlier version number than the API that your client is using.
BrokerInTerritoryExceptionYou have attempted to destroy a Broker that is currently part of a territory or you have attempted to add a Broker to a territory when it is already a member of a territory.
BrokerInvalidAccessListExceptionThe Access Control List you specified is not valid.
BrokerInvalidBrokerNameExceptionThe Broker name you specified contains illegal characters. See the appendix in the webMethods Broker Client Java API Programmer’s Guide for details on naming rules.
BrokerInvalidClientGroupNameExceptionThe client group name you specified contains illegal characters. See the appendix in the webMethods Broker Client Java API Programmer’s Guide for details on naming rules.
BrokerInvalidLogConfigExceptionThe log configuration object you have specified is not valid.
BrokerInvalidClusterNameExceptionThe cluster name you specified when creating a cluster is not valid. See the appendix in the webMethods Broker Client Java API Programmer’s Guide for details on naming rules.
webMethods Broker Administration Java API Programmer’s Guide Version 8.2 463
A API Exceptions
BrokerInvalidNameExceptionThe application name you specified when creating a Broker client is not valid. See the appendix in the webMethods Broker Client Java API Programmer’s Guide for details on naming rules.
BrokerInvalidTerritoryNameExceptionThe application name you specified when creating a territory is not valid. See the appendix in the webMethods Broker Client Java API Programmer’s Guide for details on naming rules.
BrokerNotInClusterExceptionYou have attempted to create or destroy a cluster gateway, but the Broker you have specified is not a member of any cluster.
You have specified a Broker that is not a member of any territory when attempting to add a Broker to or remove a Broker from a territory.
This error may also occur if you attempt to list the territories, territory gateways, shared event types, or territory statistics for a Broker that is not a member of any territory.
BrokerNotInTerritoryExceptionYou have attempted to create or destroy a territory gateway, but the Broker you have specified is not a member of any territory.
You have specified a Broker that is not a member of any territory when attempting to add a Broker to or remove a Broker from a territory.
This error may also occur if you attempt to list the territories, territory gateways, shared event types, or territory statistics for a Broker that is not a member of any territory.
BrokerUnknownBrokerNameExceptionYou have attempted to create or modify a territory gateway, but the remote half of the gateway has not yet been established and the remote Broker could not be found. You should start the remote Broker and attempt the operation again.
BrokerUnknownClusterExceptionYou have attempted to create or modify a cluster, but the cluster with the name you specified cannot be found.
This error might also occur if Broker did not find a gateway to the cluster you specified.
BrokerUnknownTerritoryExceptionYou have attempted to create or modify a territory, but the specified territory cannot be found.
This error might also occur if Broker did not find a gateway to the territory you specified.
464 webMethods Broker Administration Java API Programmer’s Guide Version 8.2