Title Page

webMethods Broker Administration Java API Programmers Guide

Version 8.2

April 2011

Copyright & Document ID

This document applies to webMethods Broker Version 8.2 and to all subsequent releases. Specifications contained herein are subject to change and these changes will be reported in subsequent release notes or new editions. Copyright 2001-2011 Software AG, Darmstadt, Germany and/or Software AG USA, Inc., Reston, VA, United States of America, and/or their licensors. Detailed information on trademarks and patents owned by Software AG and/or its subsidiaries is located at http://documentation.softwareag.com/legal/. Use of this software is subject to adherence to Software AG's licensing conditions and terms. These terms are part of the product documentation, located at http://documentation.softwareag.com/legal/ and/or in the root installation directory of the licensed product(s). This software may include portions of third-party products. For third-party copyright notices and license terms, please refer to License Texts, Copyright Notices and Disclaimers of Third-Party Products. This document is part of the product documentation, located at http://documentation.softwareag.com/legal/and/or in the root installation directory of the licensed product(s).

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

Table of Contents
About this Guide . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Document Conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Documentation Installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Online Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1. Managing Broker Event Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Understanding the BrokerAdminTypeDef . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Listing Event Type Definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Getting Multiple Event Type Definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Getting Event Type Definitions by Scope . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Getting Event Type Statistics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Creating and Modifying Event Type Definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Modifying Event Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Creating or Modifying Multiple Event Type Definitions . . . . . . . . . . . . . . . . . . . . . . . . . Destroying Event Type Definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Destroying Multiple Event Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Event Type Infosets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Setting Event Type Infosets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Creating or Modifying Multiple Infosets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Destroying Infosets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Destroying Multiple Infosets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2. Getting Started . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Overview of the webMethods Broker Administration API . . . . . . . . . . . . . . . . . . . . . . . . . . BrokerServerClient . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . BrokerAdminClient . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Monitoring Brokers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Managing Security Configurations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Managing Territories . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Managing Clusters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Managing Configurations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Using the Administration API for Java . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Compatibility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Application Development with webMethods Broker . . . . . . . . . . . . . . . . . . . . . . . . . . . Application Deployment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . webMethods Broker Java API Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3. Managing Brokers and Broker Servers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29 29 30 30 33 34 34 35 36 36 37 37 38 39 39 39 40 40 40 40 41 43 44 44 45 46 46 46 46 47 47 47 47 47 48 48 49 50

webMethods Broker Administration Java API Programmers Guide Version 8.2

Understanding Broker Server Clients . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Creating a BrokerServerClient . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Destroying a BrokerServerClient . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Connection Notification . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Defining a Callback Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Registering the Callback Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Un-Registering Callback Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Managing a Broker Server Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Getting Broker Server Statistics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Getting System Usage Statistics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Getting and Setting the Default Broker . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Getting and Setting Log Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Getting the Port Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Getting and Setting the License . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Starting and Stopping the Host Process . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Managing Security Configurations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Managing Brokers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Using Change Locks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Listing all Brokers on a Host . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Creating and Destroying Brokers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4. Managing Broker Clients . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Understanding BrokerAdminClients . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Creating a BrokerAdminClient . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Destroying a BrokerAdminClient . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Using Multiple BrokerAdminClients . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Disconnecting a BrokerAdminClient . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Reconnecting a BrokerAdminClient . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Using the newOrReconnectAdmin Method . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Broker Administration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Destroying a Broker . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Getting and Setting the Broker Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Getting Broker Statistics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Broker Client Administration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Obtaining Broker Client Identifiers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Getting Broker Client Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Creating Broker Clients . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Reconnecting a Remote Broker . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Disconnecting Broker Clients . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Disconnecting by Session Identifier . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Destroying Broker Clients . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Client State Sharing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Setting the Last-published Sequence Number . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Clearing a Broker Client's Queue . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

50 50 51 51 51 51 52 52 52 53 53 54 54 55 55 55 55 55 56 57 59 60 60 60 62 62 63 63 64 64 64 65 65 66 66 67 68 68 68 69 70 70 70 71

webMethods Broker Administration Java API Programmers Guide Version 8.2

Broker Client Subscriptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Listing Subscriptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Testing the Existence of a Subscription . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Creating Subscriptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Destroying Subscriptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Getting Broker Client Statistics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Getting Broker Client Infosets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5. Managing Client Groups . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Listing Client Groups . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Listing Client Identifiers by Group . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Getting Client Group Statistics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Creating and Destroying Client Groups . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Life Cycle . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Storage Type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Setting Client Group Descriptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Destroying Client Groups . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . BrokerClientGroupInfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Controlling Event Publications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Controlling Event Subscriptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Controlling Group Access . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6. Managing Security Configurations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Access Control Lists . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Getting and Setting Authenticator Names . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Getting and Setting Names . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Converting to a String . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Broker Server Security Configurations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Retrieving and Setting Broker Server Security Configurations . . . . . . . . . . . . . . . . . . . Retrieving and Setting Broker Server ACLs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Client Group Security Configurations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Obtaining Security Information for Client Sessions . . . . . . . . . . . . . . . . . . . . . . . . . . . Territory Security Configurations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Setting Territory Security . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Territory ACLs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Territory Gateway Security Configurations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Setting Territory Security . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Territory Gateway ACLs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Cluster Security Configurations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Setting Cluster Security . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Cluster ACLs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Cluster Gateway Security Configurations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Setting Cluster Security . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

71 71 71 71 72 72 73 75 76 76 77 77 78 78 79 79 79 80 80 81 82 83 84 84 85 85 86 86 86 87 87 87 88 88 88 89 89 89 89 89 90 90 90

webMethods Broker Administration Java API Programmers Guide Version 8.2

Cluster Gateway ACLs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91 7. Managing Broker Territories . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Using Territories . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Creating a New Territory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Adding a Broker to an Existing Territory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Removing a Broker from a Territory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Getting Territory Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Listing Brokers in a Territory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Obtaining Territory Statistics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Maintaining a Connection Between Brokers in a Territory . . . . . . . . . . . . . . . . . . . . . . Activating the Keep-Alive Feature between Territory Brokers . . . . . . . . . . . . . . . . Checking the Keep-Alive Settings for a Broker . . . . . . . . . . . . . . . . . . . . . . . . . . . Setting Territory Security . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Using Territory Gateways . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Creating and Destroying Gateways . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Setting Shared Event Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Listing Local Gateways . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Listing All Gateways . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Managing Event Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Obtaining Gateway Statistics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Maintaining a Connection Between Gateway Brokers . . . . . . . . . . . . . . . . . . . . . . . . . Activating the Keep-Alive Feature between Gateway Brokers . . . . . . . . . . . . . . . Checking the Keep-Alive Settings for a Gateway Broker . . . . . . . . . . . . . . . . . . . Pausing a Gateway Broker . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Pausing Traffic in Both Directions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Pausing Traffic to and from Multiple Territories . . . . . . . . . . . . . . . . . . . . . . . . . . . Unpausing a Gateway Broker . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Checking the Current Pause Setting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Static Gateway Forwarding . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Refusing Document Type Updates Across a Gateway . . . . . . . . . . . . . . . . . . . . . . . . . Update Refusal Classes and Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Synchronizing Updates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Setting Territory Gateway Security . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8. Managing Broker Clusters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Using Clusters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Creating a New Cluster . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Adding a Broker to an Existing Cluster . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Removing a Broker from a Cluster . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Getting Cluster Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Listing Brokers in a Cluster . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Obtaining Cluster Statistics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93 94 94 94 95 95 95 96 96 96 96 97 97 97 98 99 99 99 99 100 100 100 101 101 101 101 102 102 102 102 103 103 104 105 106 106 106 106 107 107 107 107

webMethods Broker Administration Java API Programmers Guide Version 8.2

Maintaining a Connection Between Brokers in a Cluster . . . . . . . . . . . . . . . . . . . . . . . Activating the Keep-Alive Feature between Cluster Brokers . . . . . . . . . . . . . . . . . Checking the Keep-Alive Settings for a Broker . . . . . . . . . . . . . . . . . . . . . . . . . . . Setting Cluster Security . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Using Cluster Gateways . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Creating and Destroying Cluster Gateways . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Setting Shared Event Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Setting Primary Gateway . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Listing Local Gateways . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Listing All Gateways . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Managing Event Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Obtaining Gateway Statistics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Maintaining a Connection Between Gateway Brokers . . . . . . . . . . . . . . . . . . . . . . . . . Activating the Keep-Alive Feature between Gateway Brokers . . . . . . . . . . . . . . . Checking the Keep-Alive Settings for a Cluster Gateway Broker . . . . . . . . . . . . . Pausing a Gateway Broker . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Pausing Traffic in Both Directions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Pausing Traffic to and from Multiple Clusters . . . . . . . . . . . . . . . . . . . . . . . . . . . . Unpausing a Cluster Gateway Broker . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Checking the Current Pause Setting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Static Gateway Forwarding . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Refusing Document Type Updates Across a Gateway . . . . . . . . . . . . . . . . . . . . . . . . Update Refusal Classes and Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Synchronizing Updates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Setting Cluster Gateway Security . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9. Managing Site Configurations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Collection Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Server Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Broker Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Client Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Client Group Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Event Type Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Territory Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Territory Gateway Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10. Monitoring Broker Activity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Activity and Trace Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Activity Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Client Changes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Client Group Changes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Event Type Changes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Territory Changes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

108 108 108 108 109 109 109 110 110 110 110 111 111 111 112 112 112 113 113 113 113 114 114 114 115 117 118 118 118 119 120 121 122 122 123 125 126 126 126 127 127 128 128

webMethods Broker Administration Java API Programmers Guide Version 8.2

Trace Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Dropped Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Remotely Dropped Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Enqueued Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Remotely Enqueued Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Published Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Remotely Published Event . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Received Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Remotely Received Event . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Peek Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Insert Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Delete Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Activity Traces . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Understanding the BrokerTraceEvent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Obtaining Activity Traces . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Broker Logging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Understanding the BrokerLogConfig . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Understanding the BrokerLogEntry . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Broker Server Logs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Obtaining Log Entries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Obtaining Log Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Deleting Log Entries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11. Queue Browser . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Client Queue Browser . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Using Client Queue Browser . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Forwarding Queue Browser . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Using Forwarding Queue Browser . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . BrokerAdminClient . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . BrokerClient . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . BrokerQueueBrowser and BrokerClientQueueBrowser . . . . . . . . . . . . . . . . . . . . . . . . . . . . BrokerLockedQueueBrowser and BrokerLockedClientQueueBrowser . . . . . . . . . . . . . . . . Creating and Closing Client Queue Browsers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . For a Client Queue Browser . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . For an Administrative Queue Browser With No Lock . . . . . . . . . . . . . . . . . . . . . . . . . . For a Administrative Queue Browser With a Lock . . . . . . . . . . . . . . . . . . . . . . . . . . . . Creating and Closing Forwarding Queue Browsers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . For an Administrative Queue Browser With No Lock . . . . . . . . . . . . . . . . . . . . . . . . . . Acquiring a Queue Lock . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Releasing a Queue Lock . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Queue Position . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Filters on a Queue Browser . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Setting a Single Filter on Queue Browser . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Setting Multiple Filters on Queue Browser . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

129 129 130 130 131 131 132 132 133 133 134 134 134 135 135 135 136 137 137 137 138 138 139 140 140 141 142 144 145 145 146 147 148 148 149 150 151 152 153 153 153 154 155 155

webMethods Broker Administration Java API Programmers Guide Version 8.2

Resetting Filters on Queue Browser . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Viewing Currently Set Filters on Queue Browser . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Viewing Queue Content . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Viewing a Client's Own Queue Content . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Administratively Viewing Contents of an Unlocked Client Queue . . . . . . . . . . . . . . . . Administratively Viewing Contents of a Locked Client Queue . . . . . . . . . . . . . . . . . . . Administratively Viewing Contents of an Unlocked Forwarding Queue . . . . . . . . . . . . Administratively Viewing Contents of a Locked Forwarding Queue . . . . . . . . . . . . . . . Identifying "Unacknowledged" Documents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Rearranging Queue Content . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Modifying Documents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Inserting Documents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Deleting Documents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Unblocking the Forwarding Queue in a Territory or Cluster . . . . . . . . . . . . . . . . . . . . . Unblocking the Forwarding Queue in a Territory Gateway or Cluster Gateway . . . . . . 12. Java API Administration Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . AccessControlList . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Constructors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . BrokerAccessControlList . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . BrokerAccessControlList . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . getAuthNames . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . getAuthNameState . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . getUserNames . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . getUserNameState . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . setAuthNames . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . setAuthNameState . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . setAuthNameStates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . setUserNames . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . setUserNameState . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . setUserNameStates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . toString . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . toString . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . BrokerAdminClient . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Constants . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Constructor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . BrokerAdminClient . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . abort Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . abortForced . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . abortForced . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . acquire Method . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . acquireChangeLock . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . add Method . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

156 157 158 158 159 161 162 164 165 166 166 168 169 170 171 173 175 175 175 175 175 175 175 176 176 176 177 177 178 178 179 179 180 180 180 180 180 182 182 182 183 183 183 184

webMethods Broker Administration Java API Programmers Guide Version 8.2

addBrokerToCluster . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . check Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . checkAndRestartForwarding . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . checkAndRestartForwarding . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . clear Method . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . clearClientQueueById . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . commit Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . commitForced . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . commitForced . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . create Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . createClient . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . createClientGroup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . createClientQueueBrowser . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . createClientSubscriptionById . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . createClientSubscriptionsById . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . createCluster . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . createClusterGateway . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . createForwardQueueBrowser . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . createLockedClientQueueBrowser . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . createLockedForwardQueueBrowser . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . createTerritory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . createTerritoryGateway . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . delete Method . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . deleteLogEvents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . destroy Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . destroyBroker . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . destroyClientById . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . destroyClientGroup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . destroyClientSubscriptionById . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . destroyClientSubscriptionsById . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . destroyClusterGateway . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . destroyEventType . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . destroyEventTypeInfoset . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . destroyEventTypeInfosets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . destroyEventTypes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . destroyTerritoryGateway . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . disconnect Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . disconnectClientById . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . disconnectClientSessionById . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . does Method . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . doesClientSubscriptionExistById . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . forget Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . forgetForced . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . forgetForced . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . forgetForced . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

184 185 185 185 186 186 186 186 187 187 187 188 189 190 191 192 193 194 195 195 196 197 198 198 198 198 199 199 200 201 202 203 204 204 205 206 207 207 208 208 208 209 209 210 210

10

webMethods Broker Administration Java API Programmers Guide Version 8.2

get Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . getActivityTraces . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . getAllClusterGateways . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . getAllQueueStats . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . getAllTerritoryGateways . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . getBrokerDescription . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . getBrokersInCluster . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . getBrokersInTerritory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . getBrokerStats . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . getClientGroupACL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . getClientGroupCanPublishList . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . getClientGroupCanSubscribeList . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . getClientGroupInfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . getClientGroupInfos . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . getClientGroupLogAcknowledgeList . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . getClientGroupLogPublishList . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . getClientGroupNames . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . getClientGroupStats . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . getClientGroupsWhichCanPublish . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . getClientGroupsWhichCanSubscribe . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . getClientIds . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . getClientIdsByClientGroup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . getClientIdsWhichAreSubscribed . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . getClientInfoById . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . getClientInfosById . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . getClientInfosetById . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . getClientQueueBrowsers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . getClientQueueLock . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . getClientStatsById . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . getClientSubscriptionsById . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . getClusterACL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . getClusterGatewayACL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . getClusterGatewayKeepAlive . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . getClusterGatewayRefuseAllUpdates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . getClusterGatewaySharedEventTypes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . getClusterGatewayStats . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . getClusterInfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . getClusterStaticGatewayForwarding . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . getClusterStats . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . getEventAdminTypeDef . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . getEventAdminTypeDefs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . getEventAdminTypeDefsByScope . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . getEventLogging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . getEventTypeStats . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . getHeuristicTransactions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

210 210 211 211 213 213 214 214 215 217 217 218 218 219 219 220 220 221 221 222 223 223 224 224 225 225 226 226 227 228 229 229 230 231 231 232 235 235 236 239 239 240 241 241 242

webMethods Broker Administration Java API Programmers Guide Version 8.2

11

getLocalClusterGateways . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . getLocalTerritoryGateways . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . getLogEvents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . getLogLength . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . getPostPrepareTimeout . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . getPostPrepareTimeoutAction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . getPrePrepareTimeout . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . getRecoverMode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . getRemoteBrokerKeepAlive . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . getStaticGatewayForwarding . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . getTerritoryACL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . getTerritoryGatewayACL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . getTerritoryGatewayKeepAlive . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . getTerritoryGatewayRefuseAllUpdates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . getTerritoryGatewayRefuseEventTypeUpdates . . . . . . . . . . . . . . . . . . . . . . . getTerritoryGatewaySharedEventTypes . . . . . . . . . . . . . . . . . . . . . . . . . . . . getTerritoryGatewayStats . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . getTerritoryInfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . getTerritoryStats . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . getTransactions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . getTransactionsByClient . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . join method . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . joinTerritory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . leave Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . leaveCluster . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . leaveTerritory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . new Method . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . newOrReconnectAdmin . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . reconnect Method . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . reconnectAdmin . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . release Method . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . releaseChangeLock . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . remove Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . removeBrokerFromCluster . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . removeBrokerFromTerritory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . set Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . setBrokerDescription . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . setClientGroupAccessLabelRequired . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . setClientGroupACL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . setClientGroupCanPublishList . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . setClientGroupCanSubscribeList . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . setClientGroupDescription . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . setClientGroupLogAcknowledgeList . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . setClientGroupLogPublishList . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . setClientGroupRequiredEncryption . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

243 244 244 245 245 245 246 246 246 247 247 248 248 249 250 250 251 254 255 258 259 260 260 261 261 262 263 263 264 264 266 266 266 266 267 268 268 269 270 270 271 272 273 273 274

12

webMethods Broker Administration Java API Programmers Guide Version 8.2

setClientInfosetById . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . setClientLastPublishSequenceNumberById . . . . . . . . . . . . . . . . . . . . . . . . . . setClientStateShareLimitById . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . setClusterACL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . setClusterGatewayACL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . setClusterGatewayKeepAlive . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . setClusterGatewayPause . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . setClusterGatewayRefuseAllUpdates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . setClusterGatewaySecurity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . setClusterGatewaySharedEventTypes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . setClusterPrimaryGateway . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . setClusterSecurity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . setClusterStaticGatewayForwarding . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . setEventAdminTypeDef . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . setEventAdminTypeDefs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . setEventLogging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . setEventTypeInfoset . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . setEventTypeInfosets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . setEventTypesAndClientGroups . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . setPostPrepareTimeout . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . setPostPrepareTimeoutAction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . setPrePrepareTimeout . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . setRecoverMode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . setRemoteBrokerKeepAlive . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . setStaticGatewayForwarding . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . setTerritoryACL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . setTerritoryGatewayACL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . setTerritoryGatewayKeepAlive . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . setTerritoryGatewayPause . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . setTerritoryGatewayRefuseAllUpdates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . setTerritoryGatewayRefuseEventTypeUpdates . . . . . . . . . . . . . . . . . . . . . . . setTerritoryGatewaySecurity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . setTerritoryGatewaySharedEventTypes . . . . . . . . . . . . . . . . . . . . . . . . . . . . setTerritorySecurity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . BrokerAdminTypeDef . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Constructors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . BrokerAdminTypeDef . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . BrokerAdminTypeDef . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . BrokerAdminTypeDef . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . BrokerAdminTypeDef . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . clearField . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . clearFields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . clearModificationFlag . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . getBaseTypeName . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

274 275 276 277 278 279 280 281 281 282 284 284 285 286 286 287 287 288 289 291 291 292 292 293 294 294 295 296 297 298 298 299 300 301 302 303 303 303 304 304 305 305 305 305 305

webMethods Broker Administration Java API Programmers Guide Version 8.2

13

getDescription . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . getFieldDef . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . getFieldNames . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . getFieldType . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . getScopeTypeName . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . getStorageType . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . getTimeToLive . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . getTypeName . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . hasBeenModified . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . insertFieldDef . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . isSystemDefined . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . orderFields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . renameField . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . setDescription . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . setFieldDef . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . setFieldType . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . setModificationFlag . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . setStorageType . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . setTimeToLive . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . setTypeName . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . toString . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . toString . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . BrokerAuthInfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . username . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . authenticator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Constructors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . BrokerAuthInfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . BrokerAuthInfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . BrokerAuthInfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . getAuthenticator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . getUserName . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . setAuthenticator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . setUserName . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . toString . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . toString . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . BrokerChangeLockInfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . acquired . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . client_id . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . session_id . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . lock_time . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . BrokerClientGroupInfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

306 306 306 307 307 308 308 308 308 309 309 310 310 311 312 312 313 313 313 314 314 315 315 315 315 315 315 315 316 316 316 316 316 316 316 317 317 317 317 317 317 317 318 318 318

14

webMethods Broker Administration Java API Programmers Guide Version 8.2

access_label_required . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . is_system_defined . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . life_cycle . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . required_encryption . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . storage_type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Constructors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . BrokerClientGroupInfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . BrokerClientGroupInfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . toString . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . toString . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . BrokerClientInfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . access_label . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . app_name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . authenticator_name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . can_share_state . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . client_group . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . client_id . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . high_pub_seqn . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . sessions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . shared_event_ordering . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . state_share_limit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . user_name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Constructors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . BrokerClientInfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . BrokerClientInfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . toCompleteString . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . toString . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . toString . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . BrokerClientQueueBrowser . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . browseEvents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . closeQueueBrowser . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . getBrowserInfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . getFilters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . resetFilters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . setFilter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . setFilters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . setPosition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . BrokerClientQueueBrowserInfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

318 318 318 318 318 318 319 319 319 319 320 320 320 320 320 320 320 320 320 321 321 321 321 321 321 321 322 322 322 322 322 322 323 323 323 323 324 324 324 325 325 325 326 326 326

webMethods Broker Administration Java API Programmers Guide Version 8.2

15

clientId . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . browserId . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . browserSessionId . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . locked . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . createTime . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Constructors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . BrokerClientQueueBrowserInfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . BrokerClientQueueBrowserInfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . BrokerClientSession . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . auth_info . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . auth_protocol . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . auth_version . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . connect_time . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . connection_id . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . create_time . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . encrypt_level . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . encrypt_protocol . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . encrypt_version . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ip_address . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . last_activity_time . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . platform_info . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . port . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . session_id . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ssl_certificate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Constructors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . BrokerClientSession . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . BrokerClientSession . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . toString . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . BrokerClusterGatewayInfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . accessible_clusters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . auth_type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . encrypt_level . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . gateway_broker_name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . gateway_host_name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . is_complete . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . is_local . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . is_primary_gateway . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . remote_broker_description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . remote_broker_name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . remote_cluster_name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . remote_host_name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

326 326 327 327 327 327 327 327 327 328 328 328 328 328 328 328 328 328 329 329 329 329 329 329 329 329 329 330 330 330 331 331 331 331 331 331 331 331 332 332 332 332 332 332 332

16

webMethods Broker Administration Java API Programmers Guide Version 8.2

toString . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . toString . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . BrokerClusterInfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . auth_type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . cluster_name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . encrypt_level . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . isLocalPublish . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Constructor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . BrokerClusterInfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . BrokerClusterInfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . toString . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . toString . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . BrokerCompleteBroker . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . broker_name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . brokers_in_territory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . client_groups . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . clients . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . event_types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . is_default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . territory_name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Constructors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . BrokerCompleteBroker . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . BrokerCompleteBroker . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . deepRefresh . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . deepRetrieve . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . deepStore . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . refresh . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . retrieve . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . store . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . toString . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . toString . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . write . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . BrokerCompleteClient . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . client_info . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . infoset . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . replace_subscriptions_on_store . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . subscriptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Constructors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . BrokerCompleteClient . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

332 333 333 333 333 333 333 333 334 334 334 334 334 334 334 334 334 335 335 335 335 335 335 335 335 335 336 336 336 336 337 338 338 339 339 340 340 340 341 341 341 341 341 341 341

webMethods Broker Administration Java API Programmers Guide Version 8.2

17

BrokerCompleteClient . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . refresh . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . retrieve . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . store . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . toString . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . toString . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . write . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . BrokerCompleteClientGroup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . acl . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . can_publish . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . can_subscribe . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . client_group_info . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ignore_change_errors_on_store . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . replace_lists_on_store . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Constructors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . BrokerCompleteClientGroup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . BrokerCompleteClientGroup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . refresh . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . retrieve . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . store . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . toString . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . toString . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . write . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . BrokerCompleteCollection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . acls . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . brokers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . client_groups . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . clients . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . event_types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . servers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Constructors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . BrokerCompleteCollection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . read . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . readFile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . toString . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . toString . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . write . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . writeVersionNumber . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . BrokerCompleteEventType . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

341 342 342 342 343 344 344 345 345 345 345 346 346 346 346 346 346 346 346 347 347 347 348 349 349 349 350 350 350 350 350 350 351 351 351 351 351 351 352 352 352 353 353 354 354

18

webMethods Broker Administration Java API Programmers Guide Version 8.2

infosets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . replace_infosets_on_store . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . type_def . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Constructors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . BrokerCompleteEventType . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . BrokerCompleteEventType . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . refresh . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . retrieve . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . store . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . toString . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . toString . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . write . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . BrokerCompleteServer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . acl . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . brokers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . host_name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . license_key . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . log_config . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . port . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ssl_config . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Constructors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . BrokerCompleteServer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . deepRefresh . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . deepRetrieve . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . deepStore . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . refresh . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . retrieve . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . store . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . toString . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . toString . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . write . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . BrokerCompleteTerritory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . acl . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . info . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . other_brokers_in_territory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Constructors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . BrokerCompleteTerritory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . BrokerCompleteTerritory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . refresh . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

354 354 354 355 355 355 355 355 356 356 357 357 358 358 358 358 358 358 359 359 359 359 359 359 359 359 359 360 361 363 363 364 365 365 365 366 366 366 366 366 366 366 366 367 367

webMethods Broker Administration Java API Programmers Guide Version 8.2

19

retrieve . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . store . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . toString . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . toString . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . write . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . BrokerCompleteTerritoryGateway . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . acl . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . info . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . remote_can_publish . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Constructors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . BrokerCompleteTerritoryGateway . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . BrokerCompleteTerritory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . refresh . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . retrieve . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . store . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . toString . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . toString . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . write . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . BrokerFilterDescriptor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . eventTypeName . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . filterExpr . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Constructors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . BrokerFilterDescriptor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . BrokerFilterDescriptor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . toString . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . BrokerForwardQueueBrowser . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . browseEvents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . closeQueueBrowser . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . getBrowserInfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . getFilters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . resetFilters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . setFilter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . setFilters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . setPosition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . BrokerInfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . broker_host . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . broker_name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . cluster_name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

367 368 368 368 369 369 370 370 370 370 370 370 370 371 371 371 372 373 373 374 374 374 374 374 375 375 375 375 375 375 375 375 376 376 376 377 377 377 378 378 378 378 378 378 379

20

webMethods Broker Administration Java API Programmers Guide Version 8.2

territory_name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Constructors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . BrokerInfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . BrokerInfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . BrokerJoinFailureInfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . client_group_names . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . event_type_names . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Constructors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . BrokerLockedClientQueueBrowser . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . deleteEvents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . insertEventsAtHead . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . insertEventsAtTail . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . modifyEvents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . BrokerLockedForwardQueueBrowser . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . deleteEvents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . insertEventsAtTail . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . modifyEvents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . BrokerLockedQueueBrowser . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . deleteEvents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . insertEventsAtHead . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . insertEventsAtTail . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . modifyEvents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . BrokerLogConfig . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Constructors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . BrokerLogConfig . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . BrokerLogConfig . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . clearLogOutput . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . clearLogOutputs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . clearLogTopic . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . clearLogTopics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . getLogOutput . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . getLogOutputs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . getLogTopic . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . getLogTopics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . setLogOutput . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . setLogOutput . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . setLogTopic . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . setLogTopic . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . toString . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

379 379 379 379 379 380 380 380 380 380 380 380 381 381 382 383 383 383 384 384 385 385 385 386 386 387 387 388 388 388 388 389 389 389 389 390 390 391 391 391 392 392 393 393 394

webMethods Broker Administration Java API Programmers Guide Version 8.2

21

toString . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . BrokerLogConfigEntry . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . enabled . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . value . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Constructors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . BrokerLogConfigEntry . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . BrokerLogConfigEntry . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . BrokerMonitorClient . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Constant . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Constructors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . BrokerMonitorClient . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . BrokerMonitorClient . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . destroy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . getHostName . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . getPort . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . getServerLogEntries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . getServerLogStatus . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . getServerRunStatus . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . getServers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . getVersion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . getVersionNumber . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . pruneMonitorLog . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . reloadConfig . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . reloadConfigForServer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . startServer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . toString . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . BrokerProcessInfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . data_directory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . exectuable_name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Constructors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . BrokerProcessInfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . BrokerProcessInfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . BrokerQueueBrowser . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . browseEvents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . closeQueueBrowser . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . getBrowserInfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . getFilters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . resetFilters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . setFilter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . setFilters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

394 394 394 394 394 395 395 395 395 395 396 396 396 396 397 397 397 397 397 398 399 399 399 400 400 400 400 401 401 401 401 401 401 402 402 402 402 402 402 403 403 403 404 404 404

22

webMethods Broker Administration Java API Programmers Guide Version 8.2

setPosition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . BrokerQueueBrowserInfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . clientId . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . browserId . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . browserSessionId . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . locked . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . createTime . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Constructors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . BrokerQueueBrowserInfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . BrokerQueueBrowserInfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . BrokerServerClient . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Constructors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . BrokerServerClient . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . createBroker . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . destroy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . getActivePort . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . getActiveProcessInfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . getActiveSSLConfig . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . getActiveSSLConfigV2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . getActiveSSLIdentity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . getBasicAuthIdentity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . getBasicAuthStatus . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . getSavedSSLidentity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . getAdminACL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . getBrokers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . getDefaultBrokerName . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . getDescription . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . getDNsFromCertFile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . getFIPSMode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . getHostName . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . getLicense . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . getLicenseContent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . getLogConfig . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . getPublicationProcessingState . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . getRootDNsFromCertFile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . getDNFromKeyStore . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . getIssuerDNFromKeystore . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . getRootDNsFromTrustStore . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . getSavedSSLConfig . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . getSavedSSLConfigV2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . getSavedSSLIdentity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . getServerLogEntries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

405 405 405 405 405 406 406 406 406 406 406 406 407 407 407 408 408 408 409 409 409 410 410 411 411 412 412 412 413 413 413 414 415 415 415 416 416 416 417 418 418 418 419 419 420

webMethods Broker Administration Java API Programmers Guide Version 8.2

23

getServerLogStatus . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . getServerProcessRunStatus . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . getServerProcessRunStatus . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . getServerVersionNumber . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . getSSLStatus . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . getStats . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . getUsageStats . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . getVersion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . pruneServerLog . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . registerConnectionCallback . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . resumePublishProcessing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . setAdminACL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . setBasicAuthIdentity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . setDefaultBrokerName . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . setDescription . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . setLicense . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . setLicenseContent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . setLicenseFile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . setLogConfig . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . setSSLConfig . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . setSSLConfig . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . setSSLConfig . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . startServerProcess . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . startServerProcess . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . stopProcess . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . toString . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . BrokerServerConnectionCallback . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . handleHostConnectionChange . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . BrokerServerLogEntry . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Constants . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . entry_msg_id . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . entry_msg_text . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . entry_type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . time_stamp . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . toString . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . BrokerServerLogInfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . first_entry . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . last_entry . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . num_entries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . BrokerSetFailureInfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

421 421 422 423 423 423 425 427 427 428 428 429 429 430 430 431 431 432 432 433 434 435 436 436 437 438 438 438 438 439 439 439 439 439 439 440 440 440 440 440 440 440 440 440 441

24

webMethods Broker Administration Java API Programmers Guide Version 8.2

client_group_names_to_destroy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . client_group_names_to_modify . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . event_type_names_to_destroy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . event_type_names_to_modify . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . failure_type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Constructor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . BrokerSetFailureInfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . BrokerSharedEventTypeInfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . accept_publish . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . accept_subscribe . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . event_type_name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . is_synchronized . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . subscribe_filter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Constructors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . BrokerSharedEventTypeInfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . BrokerSharedEventTypeInfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . toString . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . BrokerSharedEventTypeRefuseUpdateInfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Constructor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . BrokerSharedEventTypeRefuseUpdateInfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . BrokerSSLCertificate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . begin_date . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . distinguished_name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . end_date . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . issuer_distinguished_name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . serial_number . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . status . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Constructors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . BrokerSSLCertificate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . BrokerSSLCertificate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . BrokerSSLConfig . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . certificate_file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . distinguished_name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . issuer_distinguished_name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . password . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Constructors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . BrokerSSLConfig . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . BrokerSSLConfig . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . BrokerSSLConfigV2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . CRLType . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

441 441 441 441 441 441 441 441 442 442 442 442 442 442 442 442 443 443 443 443 443 443 444 444 444 444 444 445 445 445 445 445 445 446 446 446 446 446 446 446 446 447 447 447 447

webMethods Broker Administration Java API Programmers Guide Version 8.2

25

KeystoreType . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . TruststoreType . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . SSLProtocol . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Constructors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . BrokerSSLConfigV2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . BrokerSSLConfigV2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . getCipherSuites . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . setCipherSuites . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . getCRL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . setCRL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . getCRLType . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . setCRLType . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . getKeystore . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . setKeystore . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . getKeystorePassword . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . setKeystorePassword . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . getKeystoreType . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . setKeystoreType . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . getSslProtocol . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . setSslProtocol . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . getTruststore . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . setTruststore . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . getTruststoreType . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . setTruststoreType . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . setTruststoreType . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . getVerifyDepth . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . setVerifyDepth . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . toString . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . BrokerSSLIdentity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . getDN . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . getIssuerDN . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . BrokerSSLStatus . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . error_string . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . level . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . status . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Constructors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . BrokerSSLStatus . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . BrokerSSLStatus . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . BrokerTerritoryGatewayInfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . accessible_territories . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . auth_type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

447 447 447 448 448 448 448 448 448 448 448 448 449 449 449 449 449 449 449 450 450 450 450 450 451 451 451 451 451 451 452 452 452 452 452 452 452 452 453 453 453 453 454 454 454

26

webMethods Broker Administration Java API Programmers Guide Version 8.2

encrypt_level . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . gateway_broker_name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . gateway_host_name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . is_complete . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . is_local . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . is_primary_gateway . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . remote_broker_description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . remote_broker_name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . remote_host_name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . remote_territory_name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . toString . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . toString . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . BrokerTerritoryInfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . auth_type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . encrypt_level . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . isLocalPublish . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . territory_name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Constructor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . BrokerTerritoryInfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . toString . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . toString . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . BrokerTraceEvent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Constants . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . app_name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . broker_host . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . broker_name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . client_group . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . client_id . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . dest_client_id . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . encrypt_level . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . event_id . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . event_type_name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . has_tag . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ip_address . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . is_authenticated . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . key . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . other_string . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . recv_client_id . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . seqn . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . session_count . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . session_id . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

454 454 454 454 454 454 455 455 455 455 455 455 455 456 456 456 456 456 456 456 456 457 457 457 457 457 458 458 458 458 459 459 459 459 459 460 460 460 460 460 460 460 461 461 461

webMethods Broker Administration Java API Programmers Guide Version 8.2

27

tag . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . track_id . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Constructor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . BrokerTraceEvent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . toString . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

461 461 461 461 462 462

A. API Exceptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 463

28

webMethods Broker Administration Java API Programmers Guide Version 8.2

About this Guide

The webMethods Broker Administration Java API Programmers 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 Bold Narrowfont UPPERCASE Italic Description Identifies elements on a screen. Identifies storage locations for services on webMethods Integration Server, using the convention folder.subfolder:service. Identifies keyboard keys. Keys you must press simultaneously are joined with a plus sign (+). 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. 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 (...).

Monospace font

{}

| [] ...

webMethods Broker Administration Java API Programmers 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. For webMethods... 6.x 7.x 8.x The documentation is downloaded to... The installation directory of each product. A central directory named _documentation in the main installation directory (webMethods by default). A central directory named _documentation in the main installation directory (Software AG by default).

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. If you want to... Access the latest version of product documentation. Go to... Software AG Documentation Web site http://documentation.softwareag.com

30

webMethods Broker Administration Java API Programmers Guide Version 8.2

About this Guide

If you want to... 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. 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.

Go to... Empower Product Support Web site https://empower.softwareag.com

Software AG Developer Community for webMethods http://communities.softwareag.com/

webMethods Broker Administration Java API Programmers Guide Version 8.2

31

About this Guide

32

webMethods Broker Administration Java API Programmers Guide Version 8.2

Managing Broker Event Types

34 34 35 37 37 39 40 40

Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Understanding the BrokerAdminTypeDef . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Listing Event Type Definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Getting Event Type Statistics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Creating and Modifying Event Type Definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Destroying Event Type Definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Event Type Infosets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Destroying Infosets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

webMethods Broker Administration Java API Programmers 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 Programmers 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 Programmers 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 clearField clearFields renameField clearModificationFlag hasBeenModified setModificationFlag getBaseTypeName getScopeTypeName Returns the event type name, without any event scope qualifier. Returns the event type's scope name. Renames a field within a BrokerAdminTypeDef object. Manages the modification flag, which is used to track changes made to the event type definition. Description Clears one or all fields in the type definition.

34

webMethods Broker Administration Java API Programmers Guide Version 8.2

1 Managing Broker Event Types

Method getTypeName setTypeName getDescription setDescription getFieldDef setFieldDef getFieldNames getFieldType setFieldType getStorageType setStorageType getTimeToLive setTimeToLive insertFieldDef isSystemDefined orderFields toString

Description Returns the event type's fully-qualified name. Sets the fully-qualified name for the event type. Manages the description for the event type.

Given a field name, obtains or sets the field's definition.

Returns the names of the fields within an event or structure field. Manages the data type of an event field's value.

Manages the event's storage type property.

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. Adds a field to an event type or a structure field. Returns true if the event type is a system-defined type that may not be altered. Manages the order of the fields in an event type or structure field. Returns a string containing the type definition administration object in a human-readable format.

Listing Event Type Definitions

The BrokerClient.getEventTypeNames method, described in the webMethods Broker Client Java API Programmers 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,

webMethods Broker Administration Java API Programmers 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 Programmers 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 Programmers 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 types 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 Programmers 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 doesnt 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 Programmers 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 Programmers 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 Programmers 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 Programmers 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 Programmers 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 Programmers Guide Version 8.2

41

1 Managing Broker Event Types

42

webMethods Broker Administration Java API Programmers Guide Version 8.2

Getting Started
44 44 47 48

Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Overview of the webMethods Broker Administration API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Using the Administration API for Java . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . webMethods Broker Java API Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

webMethods Broker Administration Java API Programmers 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 Programmers Guide and Administering webMethods Broker.

44

webMethods Broker Administration Java API Programmers 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 Programmers 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 Configurationscovers 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 Programmers 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 Programmers 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 Programmers Guide.

webMethods Broker Administration Java API Programmers 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: Platform AIX, HP-UX, Linux, and Solaris Windows Default location Software AG_directory/common/lib/wm-brokerclient.jar Software AG_directory/common/lib/wm-g11nutils.jar Software AG_directory\common\lib\wm-brokerclient.jar Software AG_directory\common\lib\wm-g11nutils.jar

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 AIX, HP-UX, Linux, and Solaris Windows Location of webMethods Broker Java Packages Software AG_directory/Broker/doc/java_api/index.html Software AG_directory\Broker\doc\java_api\index.html

48

webMethods Broker Administration Java API Programmers Guide Version 8.2

Managing Brokers and Broker Servers

50 50 52 55

Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Understanding Broker Server Clients . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Managing a Broker Server Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Managing Brokers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

webMethods Broker Administration Java API Programmers 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 Programmers 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 Programmers 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. connect_state
CONNECT_STATE_CONNECTED CONNECT_STATE_DISCONNECTED CONNECT_STATE_RECONNECTED

Meaning The Client connection has been re-established, because automatic reconnect was enabled. The client has been disconnected. 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.

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 Programmers 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 Servers statistics */ e = c.getStats(); /* Get the total number of connections */ num_connections = e.getIntegerField( numConnections);

52

webMethods Broker Administration Java API Programmers 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 Programmers 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 Programmers 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 Programmers 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 Base port number minus 1 Base port number minus 2 Description Used for SSL connections without client authentication. Used for SSL connections with client authentication.

54

webMethods Broker Administration Java API Programmers 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
BrokerBoolean acquired;

Description Set to 1 (true) if the lock was acquired by this BrokerClient, otherwise set to 0 (false).

webMethods Broker Administration Java API Programmers Guide Version 8.2

55

3 Managing Brokers and Broker Servers

Data Member
String client_id;

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

int session_id;

BrokerDate lock_time

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

56

webMethods Broker Administration Java API Programmers 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 Programmers Guide Version 8.2

57

3 Managing Brokers and Broker Servers

58

webMethods Broker Administration Java API Programmers Guide Version 8.2

Managing Broker Clients

60 60 64 66

Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Understanding BrokerAdminClients . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Broker Administration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Broker Client Administration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

webMethods Broker Administration Java API Programmers 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 Programmers 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 Programmers 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 Programmers 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 Programmers 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 Programmers 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 Programmers 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 Programmers 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 explicitdestroy 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 Programmers 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 Programmers 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 Programmers 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 Programmers 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 Brokers 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 Programmers 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 Programmers 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 Programmers 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 Programmers 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 Programmers 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 Programmers 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 Programmers 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 Programmers 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 Programmers Guide Version 8.2

71

4 Managing Broker Clients

The BrokerSubscription class is described in the webMethods Broker Client Java API Programmers 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 Programmers 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 Programmers 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 Programmers Guide Version 8.2

73

4 Managing Broker Clients

74

webMethods Broker Administration Java API Programmers Guide Version 8.2

Managing Client Groups

76 76 77 77 78 80 80 81 82

Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Listing Client Groups . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Listing Client Identifiers by Group . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Getting Client Group Statistics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Creating and Destroying Client Groups . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . BrokerClientGroupInfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Controlling Event Publications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Controlling Event Subscriptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Controlling Group Access . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

webMethods Broker Administration Java API Programmers 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 Programmers 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 Programmers 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 Programmers 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 Programmers 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 Programmers 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 Programmers Guide Version 8.2

5 Managing Client Groups

Value
LIFECYCLE_DESTROY_ON_DISCONNECT

Description The Broker will destroy the client state whenever the connection between a Broker client and the Broker is lost. 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.

LIFECYCLE_EXPLICIT_DESTROY

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. Life Cycle
STORAGE_GUARANTEED

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

STORAGE_VOLATILE

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

webMethods Broker Administration Java API Programmers 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 Programmers 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 Programmers 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 Programmers Guide Version 8.2

Managing Security Configurations

84 84 86 87 88 89 89 90

Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Access Control Lists . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Broker Server Security Configurations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Client Group Security Configurations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Territory Security Configurations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Territory Gateway Security Configurations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Cluster Security Configurations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Cluster Gateway Security Configurations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

webMethods Broker Administration Java API Programmers 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 Programmers 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 Programmers 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 Programmers 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 2 Use the BrokerAdminClient.getClientInfoById or getClientInfosById method to obtain a BrokerClientInfo object for the particular Broker client in which you are interested. Examine each BrokerClientSession object contained in the BrokerClientInfo.sessions data member.

webMethods Broker Administration Java API Programmers Guide Version 8.2

87

6 Managing Security Configurations

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. 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 Programmers 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 Programmers 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 Programmers 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 Programmers Guide Version 8.2

91

6 Managing Security Configurations

92

webMethods Broker Administration Java API Programmers Guide Version 8.2

Managing Broker Territories

94 94 97

Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Using Territories . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Using Territory Gateways . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

webMethods Broker Administration Java API Programmers 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 Programmers Guide Version 8.2

7 Managing Broker Territories

Note: For information on territory name restrictions, see the webMethods Broker Client Java API Programmers 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 Programmers 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 Programmers 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 Programmers 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 Programmers 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 Programmers 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 Programmers 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 Programmers 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 reenabled.

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 Programmers 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 Programmers 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 Programmers 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 Programmers Guide Version 8.2

Managing Broker Clusters

106 106 109

Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Using Clusters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Using Cluster Gateways . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

webMethods Broker Administration Java API Programmers 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 Programmers 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 Programmers 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 Programmers 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 Programmers 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 Programmers 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 Programmers 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 Programmers 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 Programmers 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 reenabled.

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 Programmers 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 Programmers 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 Programmers 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 Programmers Guide Version 8.2

115

8 Managing Broker Clusters

116

webMethods Broker Administration Java API Programmers Guide Version 8.2

Managing Site Configurations

118 118 118 119 120 121 122 122 123

Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Collection Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Server Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Broker Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Client Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Client Group Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Event Type Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Territory Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Territory Gateway Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

webMethods Broker Administration Java API Programmers 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 Programmers 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. Method read readFile toString write writeVersionNumber Description Creates a BrokerCompleteCollection and initializes it from input data or from an input file containing ADL. Returns a string of ADL that describes the collection defined by this object. Writes the contents of this collection, usually to a file, in ADL format. Writes just the version number of this object.

Server Information
You can use the BrokerCompleteServer class to hold the following information about a Broker Server:

118

webMethods Broker Administration Java API Programmers 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. Method deepRefresh deepRetrieve deepStore refresh Description Refreshes this object's data members, using the specified administrative Broker client. Returns a BrokerCompleteServer object initialized using the specified administrative Broker client. Stores the information contained in this object into a Broker Server. 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. Returns a BrokerCompleteServer object initialized using the specified administrative Broker client. Server information is returned, but not information on the server's Brokers. Stores the information contained in this object into a Broker Server. Server information is stored, but not information the server's Brokers. Returns a string of ADL that describes the information contained in this object. Writes the contents of this collection, usually to a file, in ADL format.

retrieve

store

toString write

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

webMethods Broker Administration Java API Programmers 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. Method deepRefresh deepRetrieve deepStore refresh Description Refreshes this object's data members, using the specified administrative Broker client. Returns a BrokerCompleteBroker object initialized using the specified administrative Broker client. Stores the information contained in this object into a Broker. 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. Returns a BrokerCompleteBroker object initialized using the specified administrative Broker client. Stores most of the information contained in this object into a Broker Server. Returns a string of ADL that describes the information contained in this object. Writes the contents of this collection, usually to a file, in ADL format.

retrieve store toString write

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.

120

webMethods Broker Administration Java API Programmers Guide Version 8.2

9 Managing Site Configurations

Method refresh

Description 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. Returns a BrokerCompleteClient object initialized using the specified administrative Broker client. Stores most of the information contained in this object into the Broker client. Returns a string of ADL that describes the information contained in this object. Writes the contents of this collection, usually to a file, in ADL format.

retrieve store toString write

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 refresh Description 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. Returns a BrokerCompleteClientGroup object initialized using the specified administrative Broker client. Stores the information contained in this object into the Broker. Returns a string of ADL that describes the information contained in this object. Writes the contents of this collection, usually to a file, in ADL format.

retrieve store toString write

webMethods Broker Administration Java API Programmers 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. Method refresh Description 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. Returns a BrokerCompleteEventType object initialized using the specified administrative Broker client. Stores the information contained in this object into the Broker. Returns a string of ADL that describes the information contained in this object. Writes the contents of this collection, usually to a file, in ADL format.

retrieve store toString write

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 refresh Description 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 Programmers Guide Version 8.2

9 Managing Site Configurations

Method retrieve store toString write

Description Returns a BrokerCompleteTerritory object initialized using the specified administrative Broker client. Stores the information contained in this object into the Broker. Returns a string of ADL that describes the information contained in this object. Writes the contents of this collection, usually to a file, in ADL format.

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. Method refresh Description 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. Returns a BrokerCompleteTerritory object initialized using the specified administrative Broker client. Stores the information contained in this object into the Broker. Returns a string of ADL that describes the information contained in this object. Writes the contents of this collection, usually to a file, in ADL format.

retrieve store toString write

webMethods Broker Administration Java API Programmers Guide Version 8.2

123

9 Managing Site Configurations

124

webMethods Broker Administration Java API Programmers Guide Version 8.2

10

Monitoring Broker Activity

126 126 134 135 137

Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Activity and Trace Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Activity Traces . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Broker Logging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Broker Server Logs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

webMethods Broker Administration Java API Programmers 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 Programmers 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 Programmers 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. Field Name
clientId clientGroup appName stateFlags

Type
unicode_string unicode_string unicode_string int

Description The identifier of the Broker client whose state has changed. The Broker client's group affiliation. The application name associated with the Broker client. 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. The entity that authenticated the user. This will only be set if the entity making the change used an SSL connection.

authenticator

unicode_string

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.

webMethods Broker Administration Java API Programmers Guide Version 8.2

127

10 Monitoring Broker Activity

Field Name
created changed

Type
unicode_string[] unicode_string[]

Description The list of client groups that were created. The list of client groups that were changed. Changes may include modifications to the can-publish list, cansubscribe list, or ACL. The list of client groups that were destroyed. The time the change occurred. The user that made the change. The entity that authenticated the user.

destroyed changeTime user authenticator

unicode_string[] date unicode_string unicode_string

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. Field Name
created defChanged infoChanged destroyed changeTime user authenticator

Type
unicode_string[] unicode_string[] unicode_string[] unicode_string[] date unicode_string unicode_string

Description The list of event types that were created. The list of event types whose definitions were changed. The list of event types whose infosets were modified. The list of event types that were destroyed. The time the change occurred. The user that made the change. The entity that authenticated the user.

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

Type
unicode_string unicode_string

Description The name of the Broker's territory. The name of the Broker.

128

webMethods Broker Administration Java API Programmers Guide Version 8.2

10 Monitoring Broker Activity

Field Name
hostName changeFlags

Type
unicode_string int

Description The name of the Broker's host. A bit mask with one or more of the following values: 1-jointed 2-left 4-local Broker

user authenticator

unicode_string unicode_string

The user that made the change. The entity that authenticated the user.

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 Programmers 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. Field Name
clientId eventTypeName eventId pubId destId trackId tag eventByteSize

Type
unicode_string unicode_string long unicode_string unicode_string unicode_string int int

Description The Broker client's identifier. The name of the event type. The event identifier from the event. The identifier of the Broker client that delivered the event. The identifier of the intended recipient Broker client. The tracking identifier from the event. The event's tag field. The size of the event in bytes.

webMethods Broker Administration Java API Programmers 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. Field Name
brokerName brokerHost eventTypeName eventId pubId destId trackId tag eventByteSize

Type
unicode_string unicode_string unicode_string long unicode_string unicode_string unicode_string int int

Description The name of the remote Broker for which the event was enqueued. The host name where the remote Broker is running. The name of the event type. The event identifier from the event. The identifier of the Broker client that delivered the event. The identifier of the intended recipient Broker client. The tracking identifier from the event. The event's tag field. The size of the event in bytes.

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
clientId eventTypeName eventId pubId destId trackId tag eventByteSize

Type
unicode_string unicode_string long unicode_string unicode_string unicode_string int int

Description The Broker client's identifier. The name of the event type. The event identifier from the event. The identifier of the Broker client that delivered the event. The identifier of the intended recipient Broker client. The tracking identifier from the event. The event's tag field. The size of the event in bytes.

130

webMethods Broker Administration Java API Programmers 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. Field Name
brokerName brokerHost eventTypeName eventId pubId destId trackId tag eventByteSize

Type
unicode_string unicode_string unicode_string long unicode_string unicode_string unicode_string int int

Description The name of the remote Broker for which the event was enqueued. The host name where the remote Broker is running. The name of the event type. The event identifier from the event. The identifier of the Broker client that delivered the event. The identifier of the intended recipient Broker client. The tracking identifier from the event. The event's tag field. The size of the event in bytes.

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
clientId eventTypeName eventId pubId destId trackId tag eventByteSize

Type
unicode_string unicode_string long unicode_string unicode_string unicode_string int int

Description The Broker client's identifier. The name of the event type. The event identifier from the event. The identifier of the Broker client that delivered the event. The identifier of the intended recipient Broker client. The tracking identifier from the event. The event's tag field. The size of the event in bytes.

webMethods Broker Administration Java API Programmers 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. Field Name
brokerName brokerHost eventTypeName eventId pubId destId trackId tag eventByteSize

Type
unicode_string unicode_string unicode_string long unicode_string unicode_string unicode_string int int

Description The name of the remote Broker for which the event was enqueued. The host name where the remote Broker is running. The name of the event type. The event identifier from the event. The identifier of the Broker client that delivered the event. The identifier of the intended recipient Broker client. The tracking identifier from the event. The event's tag field. The size of the event in bytes.

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
clientId eventTypeName eventId pubId destId trackId tag eventByteSize

Type
unicode_string unicode_string long unicode_string unicode_string unicode_string int int

Description The Broker client's identifier. The name of the event type. The event identifier from the event. The identifier of the Broker client that published the event. The identifier of the intended recipient Broker client. The tracking identifier from the event. The event's tag field. The size of the event in bytes.

132

webMethods Broker Administration Java API Programmers 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. Field Name
brokerName brokerHost eventTypeName eventId pubId destId trackId tag eventByteSize

Type
unicode_string unicode_string unicode_string long unicode_string unicode_string unicode_string int int

Description The name of the remote Broker. The host name where the remote Broker is running. The name of the event type. The event identifier from the event. The identifier of the Broker client that published the event. The identifier of the intended recipient Broker client. The tracking identifier from the event. The event's tag field. The size of the event in bytes.

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
clientId eventTypeName eventId lockingId trackId tag eventByteSize

Type
unicode_string unicode_string long unicode_string unicode_string int int

Description The Broker client's identifier. The name of the event type. The event identifier from the event. The identifier of the Broker client that is holding a queue lock on this client. The tracking identifier from the event. The event's tag field. The size of the event in bytes.

webMethods Broker Administration Java API Programmers 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. Field Name
clientId eventTypeName eventId lockingId trackId tag eventByteSize

Type
unicode_string unicode_string long unicode_string unicode_string int Int

Description The Broker client's identifier. The name of the event type. The event identifier from the event. The identifier of the Broker client that is holding a queue lock on this client. The tracking identifier from the event. The event's tag field. The size of the event in bytes.

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. Field Name
clientId eventTypeName eventId lockingId trackId tag eventByteSize

Type
unicode_string unicode_string long unicode_string unicode_string int int

Description The Broker client's identifier. The name of the event type. The event identifier from the event. The identifier of the Broker client that is holding a queue lock on this client. The tracking identifier from the event. The event's tag field. The size of the event in bytes.

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:

134

webMethods Broker Administration Java API Programmers 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 Alert Warning Description Identifies critical messages. Identifies important messages.

webMethods Broker Administration Java API Programmers Guide Version 8.2

135

10 Monitoring Broker Activity

Level Informational

Description Identifies informational messages.

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. Method clearLogOutput clearLogOutputs clearLogTopic clearLogTopics getLogOutput clearLogOutputs getLogTopic getLogTopics setLogOutput setLogTopic toString Returns one or more BrokerLogEntry objects which represent the state of the specified log output or outputs. Returns one or more BrokerLogEntry objects which represent the state of the specified log topic or topics. Sets the value of a log output's state. Sets the value of a log topic's state. Returns a string containing the log configuration in a humanreadable format. Clears one or more entries from a specified log topic. Description Clears one or more entries from a specified log output.

136

webMethods Broker Administration Java API Programmers 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. Field Name
time_stamp entry_type entry_mesg_id entry_msg_text

Type
BrokerDate short short char *

Description The date and time that the entry was created. The entry's type. See the next table, below, for a list of possible types. The message identifier. The event identifier from the event.

Each Broker Server log entry is assigned a type as defined in the following table. Constant
SERVER_LOG_MESSAGE_UNKNOWN SERVER_LOG_MESSAGE_INFO SERVER_LOG_MESSAGE_WARNING SERVER_LOG_MESSAGE_ALERT

Description The entry has an undefined type. The entry contains an informational message. The entry contains a warning message. The entry contains an alert message.

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.

webMethods Broker Administration Java API Programmers 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. Field Name
num_entries first_entry last_entry

Type
int BrokerDate BrokerDate

Description The number of entries contained in the log. The date and time of the earliest entry contained in the log. The date and time of the most recent entry contained in the log.

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.

138

webMethods Broker Administration Java API Programmers Guide Version 8.2

11

Queue Browser
140 140 141 142 144 145 145 146 147 148 151 153 153 153 154 158 166

Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Client Queue Browser . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Using Client Queue Browser . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Forwarding Queue Browser . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Using Forwarding Queue Browser . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . BrokerAdminClient . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . BrokerClient . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . BrokerQueueBrowser and BrokerClientQueueBrowser . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . BrokerLockedQueueBrowser and BrokerLockedClientQueueBrowser . . . . . . . . . . . . . . . . . . . . Creating and Closing Client Queue Browsers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Creating and Closing Forwarding Queue Browsers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Acquiring a Queue Lock . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Releasing a Queue Lock . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Queue Position . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Filters on a Queue Browser . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Viewing Queue Content . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Rearranging Queue Content . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

webMethods Broker Administration Java API Programmers 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 2 3 A client can inspect its own queue contents without requiring any administrative privileges. An administrative client can inspect a client queue without acquiring the client's queue lock. 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. The insert operation to add documents to either the head or tail of a locked queue. The delete operation to delete documents based on their receipt sequence numbers.

2 3

140

webMethods Broker Administration Java API Programmers Guide Version 8.2

11 Queue Browser

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. 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. 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 Programmers Guide Version 8.2

141

11 Queue Browser

Data Member
String clientId

Description 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. This member contains the ID of the client that created the queue browser. For information on client IDs, see Queue Browser on page 139. This member contains the session ID of the client that created the queue browser. The value is set to true if the client queue is locked by this queue browser; otherwise, false. This member contains the date and time when the queue browser was created.

String browserId

int browserSessionId boolean locked int createTime

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 2 An administrative client can inspect a forwarding queue without acquiring the client's queue lock. 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. 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 4 The delete operation to delete documents based on their receipt sequence numbers. 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

142

webMethods Broker Administration Java API Programmers 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 Programmers 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. 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 Programmers Guide Version 8.2

11 Queue Browser

The BrokerQueueBrowserInfo object represents information of a queue browser with data members described in the following table. Data Member
String clientId String browserId

Description This member contains the ID of the client or remote Broker on which the queue browser is currently open. This member contains the ID of the client that created the queue browser. For information on client IDs, see Queue Browser on page 139. This member contains the session ID of the client that created the queue browser. The value is set to true if the client queue is locked by this queue browser; otherwise, false. This member contains the date and time when the queue browser was created.

int browserSessionId boolean locked int createTime

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.

webMethods Broker Administration Java API Programmers 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 getBrowserInfo setPosition Description Get browser information of the current queue browser. 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 Programmers Guide Version 8.2

11 Queue Browser

Method setFilters

Description 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. Reset the filter list on the current queue browser. The filter list on the queue browser will be emptied out. Get filters that are currently set for queue browse operation. The existing filters are returned in the form of BrokerFilterDescriptor objects. 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.

resetFilters getFilters

browseEvents

closeQueueBrowser

Close the queue browser and release the associated resources.

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.

webMethods Broker Administration Java API Programmers 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. Method
modifyEvents

Description Modify documents in the queue. The documents are identified by the specified receipt sequence numbers for an in-place replacement in the queue. Delete documents in the queue. The documents are identified by the receipt sequence numbers. Insert documents into the queue at head position. Insert documents into the queue at tail position.

deleteEvents insertEventsAtHead insertEventsAtTail

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.

148

webMethods Broker Administration Java API Programmers 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 Programmers 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 Programmers 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 Programmers 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 Programmers 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 Programmers 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 Programmers 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 Programmers 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 Programmers 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 Programmers 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 Programmers Guide Version 8.2

11 Queue Browser

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 Programmers Guide Version 8.2

159

11 Queue Browser

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.

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. 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 Programmers 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. 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. 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 Programmers 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 Programmers 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. 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 Programmers 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. 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. 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 Programmers 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 Programmers 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 Programmers 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 Programmers 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 Programmers 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 Programmers 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 Programmers 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. Make the Broker leave the territory, or cluster. For more information, see Removing a Broker from a Territory on page 95. Rejoin the Broker to the territory, or cluster. For more information, see Adding a Broker to an Existing Territory on page 95. Restore all the regular events to their respective forwarding queues. For more information, see Inserting Documents on page 168.

2 3 4

170

webMethods Broker Administration Java API Programmers 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. Save the gateway configuration. For more information about importing and exporting Broker metadata, see Administering webMethods Broker. 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. Reconfigure the gateway. For more information about importing and exporting Broker metadata, see Administering webMethods Broker. 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.

2 3

4 5

webMethods Broker Administration Java API Programmers Guide Version 8.2

171

11 Queue Browser

172

webMethods Broker Administration Java API Programmers Guide Version 8.2

12

Java API Administration Reference

175 180 302 315 317 318 320 323 326 327 331 333 334 340 345 350 354 358 366 369 374 375 378 379 380 383 385 387

AccessControlList . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . BrokerAdminClient . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . BrokerAdminTypeDef . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . BrokerAuthInfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . BrokerChangeLockInfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . BrokerClientGroupInfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . BrokerClientInfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . BrokerClientQueueBrowser . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . BrokerClientQueueBrowserInfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . BrokerClientSession . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . BrokerClusterGatewayInfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . BrokerClusterInfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . BrokerCompleteBroker . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . BrokerCompleteClient . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . BrokerCompleteClientGroup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . BrokerCompleteCollection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . BrokerCompleteEventType . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . BrokerCompleteServer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . BrokerCompleteTerritory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . BrokerCompleteTerritoryGateway . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . BrokerFilterDescriptor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . BrokerForwardQueueBrowser . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . BrokerInfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . BrokerJoinFailureInfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . BrokerLockedClientQueueBrowser . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . BrokerLockedForwardQueueBrowser . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . BrokerLockedQueueBrowser . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . BrokerLogConfig . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

webMethods Broker Administration Java API Programmers Guide Version 8.2

173

12 Java API Administration Reference

BrokerLogConfigEntry . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . BrokerMonitorClient . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . BrokerProcessInfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . BrokerQueueBrowser . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . BrokerQueueBrowserInfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . BrokerServerClient . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . BrokerServerConnectionCallback . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . BrokerServerLogEntry . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . BrokerServerLogInfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . BrokerSetFailureInfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . BrokerSharedEventTypeInfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . BrokerSharedEventTypeRefuseUpdateInfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . BrokerSSLCertificate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . BrokerSSLConfig . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . BrokerSSLConfigV2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . BrokerSSLIdentity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . BrokerSSLStatus . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . BrokerTerritoryGatewayInfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . BrokerTerritoryInfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . BrokerTraceEvent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

394 395 401 402 405 406 438 439 440 440 441 443 444 446 447 451 452 453 456 457

174

webMethods Broker Administration Java API Programmers 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

acl

The access list to be copied.

This is a copy constructor. Possible Exceptions

BrokerNullParameterException

Meaning The acl parameter is null.

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

webMethods Broker Administration Java API Programmers Guide Version 8.2

175

12 Java API Administration Reference

name

The distinguished name of a certificate authenticator or basic authentication alias whose state is to be returned.

Returns true if the specified authenticator or basic authentication aliasname is currently in the list. Possible Exceptions
BrokerNullParameterException

Meaning The name parameter is null.

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

name

The SSL or basic authentication user name whose state is to be returned.

Returns true if the specified name is currently in the list. Possible Exceptions
BrokerNullParameterException

Meaning The name parameter is null.

See Also: BrokerAccessControlList.setUserNameState and BrokerAccessControlList.setUserNameStates

setAuthNames
void setAuthNames( String names[]) throws BrokerException

176

webMethods Broker Administration Java API Programmers Guide Version 8.2

12 Java API Administration Reference

names

An array of strings, each containing the name of a certificate authorizing entity or basic authentication alias.

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. Possible Exceptions
BrokerInvalidNameException BrokerNullParameterException BrokerBlankParameterException

Meaning One or more of the names in the names array is invalid. The names parameter is null or any of its entries is null. The names parameter is blank, or a name in the array is blank.

See Also: BrokerAccessControlList.getAuthNames and BrokerAccessControlList.setAuthNameState

setAuthNameState
void setAuthNameState( String name, Boolean is_allowed) throws BrokerException

name is_allowed

The authenticator or basic authentication alias name to be set for this list. Determines whether the authorizer or basic authentication alias name is added or removed from the list.

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. Possible Exceptions
BrokerNullParameterException BrokerBlankParameterException

Meaning The name parameter is null. The name parameter is blank.

See Also: BrokerAccessControlList.getAuthNameState and BrokerAccessControlList.setAuthNameStates

setAuthNameStates
void setUserNames( String names[]) throws BrokerException

webMethods Broker Administration Java API Programmers Guide Version 8.2

177

12 Java API Administration Reference

name is_allowed

The authenticator or basic authentication alias name to be set for this list. Determines whether the authenticator or basic authentication alias names are to be added or removed from the list.

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. Possible Exceptions
BrokerNullParameterException BrokerBlankParameterException

Meaning The names parameter is null or an entry it contains is null. The names parameter is blank, or a name in the array is blank.

See Also: BrokerAccessControlList.getAuthNameState and BrokerAccessControlList.setAuthNameState

setUserNames
void setUserNames( String names[]) throws BrokerException

names

The SSL and basic authentication user names to be set for this list.

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. Possible Exceptions
BrokerNullParameterException BrokerBlankParameterException

Meaning The names parameter is null or any of its entries is null. The names parameter is blank, or a name in the array is blank.

See Also: BrokerAccessControlList.getUserNameState and BrokerAccessControlList.setUserNameState

setUserNameState
void setUserNameState( String name, Boolean is_allowed) throws BrokerException

178

webMethods Broker Administration Java API Programmers Guide Version 8.2

12 Java API Administration Reference

name is_allowed

The SSL or basic authentication user name to be set for this list. Determines whether the SSL or basic authentication user name is to be added or removed from the list.

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. Possible Exceptions
BrokerNullParameterException BrokerBlankParameterException

Meaning The name parameter is null. The names parameter is blank, or a name in the array is blank.

See Also: BrokerAccessControlList.getUserNames, BrokerAccessControlList.getUserNameState, BrokerAccessControlList.setUserNameState, and BrokerAccessControlList.setUserNameStates

setUserNameStates
void setNameStates( String names[] boolean is_allowed) throws BrokerException

name is_allowed

The SSL and basic authentication user names to be set for this list. Determines whether the SSL and basic authentication user names are to be added or removed from the list.

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. Possible Exceptions
BrokerNullParameterException BrokerBlankParameterException

Meaning The names parameter is null or an entry it contains is null. The names parameter is blank, or a name in the array is blank.

See Also: BrokerAccessControlList.getUserNameState, BrokerAccessControlList.setUserNames, and BrokerAccessControlList.setUserNameState.

toString
String toString()

webMethods Broker Administration Java API Programmers 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)

indent_level name

The number of 4-character spaces to use for indentation. An optional name for the access list. Can be set to null.

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

180

webMethods Broker Administration Java API Programmers Guide Version 8.2

12 Java API Administration Reference

String app_name, BrokerConnectionDescriptor desc) throws BrokerException

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. The name of the Broker to which the new Broker client will be connected. If null, the default Broker will be used. 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 destroyon-disconnect. See the webMethods Broker Client Java API Programmers Guide for more information on client identifiers. The name of the client group for the new Broker client. Client groups are discussed in Administering webMethods Broker. The name of the application that will contain the new Broker client. 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.

broker_name client_id

client_group app_name desc

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 Programmers Guide, when the BrokerAdminClient is no longer needed. Possible Exceptions
BrokerClientExistsException BrokerClientQueueBrowserException

Meaning Another Broker client is already using the specified client_id. 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 Programmers Guide Version 8.2

181

12 Java API Administration Reference

Possible Exceptions
BrokerQueueBrowserException

Meaning 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. A problem occurred establishing the connection. The specified broker_host does not exist. The client_id contains invalid characters. Permission to join the client_group was denied. A Broker could not be found on the broker_host. The broker_host, client_group, or app_name parameter is null. The specified broker_name does not exist. If broker_name was null, then there is no default Broker. The specified client_group does not exist on the Broker.

BrokerCommFailureException BrokerHostNotFoundException BrokerInvalidClientIdException BrokerNoPermissionException BrokerNotRunningException BrokerNullParameterException BrokerUnknownBrokerNameException

BrokerUnknownClientGroupException

See Also: BrokerClient.disconnect, BrokerClient.destroy, BrokerAdminClient.newOrReconnectAdmin, and BrokerAdminClient.reconnectAdmin.

Methods
abort Methods
abortForced
void abortForced(long tx_id) throws BrokerException;

tx_id

The Broker transaction context to abort.

Forcibly terminates a transaction.

182

webMethods Broker Administration Java API Programmers Guide Version 8.2

12 Java API Administration Reference

Exception
BrokerInvalidClientException BrokerInvalidTxException BrokerNoPermissionException

Description The client has been destroyed or disconnected The transaction does not exist or the transaction state does not allow it to be aborted. The client does not have sufficient permissions.

abortForced
void abortForced(long tx_ids[]) throws BrokerException;

tx_id

A list of Broker transaction contexts to abort.

Forcibly terminates a list of transactions. Exception

BrokerInvalidClientException BrokerNullParameterException BrokerInvalidTxException BrokerNoPermissionException

Description The client has been destroyed or disconnected tx_ids is null. One or more transactions do not exist or the transaction state does not allow it to be aborted. The BrokerAdminClient does not have necessary permissions on the Broker.

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.

webMethods Broker Administration Java API Programmers Guide Version 8.2

183

12 Java API Administration Reference

Possible Exceptions
BrokerIncompatibleVersionException BrokerInvalidClientException

Meaning The Broker Server does not support this operation. The BrokerAdminClient has been destroyed or disconnected.

See Also: BrokerAdminClient.releaseChangeLock

add Method
addBrokerToCluster
BrokerJoinFailureInfo addBrokerToCluster( 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. The name of the Broker whose cluster this Broker must join. This parameter may not be null.

broker_name

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
BrokerHostNotFoundException BrokerInClusterException BrokerInvalidClientException BrokerNoPermissionException

Meaning The specified broker_host does not exist. This client's Broker is already a member of a cluster. The BrokerAdminClient has been destroyed or disconnected. The BrokerAdminClient does not have permission to modify the Broker's properties or the Broker is not licensed for Broker interconnection. The Broker specified by broker_name is not a member of a cluster.

BrokerNotInClusterException

184

webMethods Broker Administration Java API Programmers Guide Version 8.2

12 Java API Administration Reference

Possible Exceptions
BrokerNullParameterException BrokerOutOfRangeException BrokerSecurityException BrokerUnknownBrokerNameException BrokerSSLClusterException

Meaning The parameter broker_host or broker_name is null. There is another Broker in the specified cluster with the same name. If the cluster requires SSL and the joining Broker does not support SSL. The specified broker_name does not exist on the specified broker_host. SSL connection error between Broker Servers.

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. Possible Exceptions
BrokerInvalidClientException BrokerNullParameterException

Meaning The BrokerAdminClient is invalid. The remote Broker name is null.

checkAndRestartForwarding
int checkAndRestartForwarding(String remote_broker_name) throws BrokerException

remote_broker_name

The name of the specific remote Broker you wish to restart.

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.

webMethods Broker Administration Java API Programmers Guide Version 8.2

185

12 Java API Administration Reference

Possible Exceptions
BrokerInvalidClientException BrokerNullParameterException

Meaning The BrokerAdminClient is invalid. The specified remote Broker name is null.

clear Method
clearClientQueueById
void clearQueue( String client_id) throws BrokerException

client_id

A string containing the client identifier whose event queue is to be cleared.

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. Possible Exceptions
BrokerInvalidClientException BrokerNoPermissionException BrokerNullParameterException BrokerUnknownClientIdException

Meaning The BrokerAdminClient has been destroyed or disconnected. Permission to delete the client's events was denied. The client_id parameter is null. The specified client does not exist on the Broker.

See Also: BrokerAdminClient.getClientStatsById

commit Methods
commitForced
void commitForced(long tx_id) throws BrokerException

186

webMethods Broker Administration Java API Programmers Guide Version 8.2

12 Java API Administration Reference

tx_id

The Broker transaction context to commit.

Forcibly commits a transaction. Exception

BrokerInvalidClientException BrokerInvalidTxException BrokerNoPermissionException

Description The BrokerAdminClient has been destroyed or disconnected. Transaction tx_id does not exist or the transaction state does not allow it to be committed. The BrokerAdminClient does not have necessary permissions on the Broker.

commitForced
void commitForced( long tx_ids[]) throws BrokerException

tx_ids

A list of Broker transaction contexts to commit.

Forcibly commits a list of transactions. Exception

BrokerInvalidClientException BrokerInvalidTxException BrokerNoPermissionException

Description The BrokerAdminClient has been destroyed or disconnected. One or more transactions do not exist or the transaction state does not allow it to be committed. The BrokerAdminClient does not have necessary permissions on the Broker.

create Methods
createClient
void createClient( String client_id, String client_group, String app_name, String user_name, String authenticator_name, BrokerConnectionDescriptor desc) throws BrokerException

client_id

The client identifier. See the webMethods Broker Client Java API Programmers Guide for more information on client identifiers.

webMethods Broker Administration Java API Programmers Guide Version 8.2

187

12 Java API Administration Reference

client_group app_name desc user_name authenticator_name

The name of the client group for the new Broker client. Client groups are discussed in Administering webMethods Broker. The name of the application that will contain the new Broker client. The connection descriptor used to set state sharing for the client. If set to null, state sharing will be disabled. The user name of the entity creating the client. The name of the authenticator that issued the certificate for user_name.

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 Programmers Guide. Possible Exceptions
BrokerClientExistsException BrokerInvalidClientException BrokerInvalidClientIdException BrokerInvalidNameException BrokerNoPermissionException BrokerNullParameterException BrokerUnknownClientGroupException

Meaning Another Broker client is already using the specified client_id. The BrokerAdminClient has been destroyed or disconnected. The client_id contains invalid characters. The app_name parameter contains invalid characters. The client does not have permission to modify clients in the specified client group. The client_id, client_group_name, or app_name parameter is null. The specified client_group does not exist.

createClientGroup
void createClientGroup( String client_group_name, int life_cycle, int storage_type) throws BrokerException

188

webMethods Broker Administration Java API Programmers Guide Version 8.2

12 Java API Administration Reference

client_group_name

The name of the client group to be created. See the webMethods Broker Client Java API Programmers Guide for details on group name restrictions. The life cycle of the clients associated with the group. Must be either LIFECYCLE_DESTROY_ON_DISCONNECT or LIFECYCLE_EXPLICIT_DESTROY. 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

life_cycle

storage_type

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. Possible Exceptions
BrokerClientGroupExistsException BrokerInvalidClientException BrokerInvalidClientGroupNameException BrokerNoPermissionException BrokerNullParameterException BrokerOutOfRangeException

Meaning A client group with the specified name already exists on the Broker. The BrokerAdminClient has been destroyed or disconnected. The specified client group name is not valid. The client does not have permission create a client group. The client_group_name parameter is null. The life_cycle or storage_parameter parameter contains an invalid value.

See Also: BrokerAdminClient.getClientGroupNames, BrokerAdminClient.setClientGroupCanPublishList, BrokerAdminClient.setClientGroupCanSubscribeList, BrokerAdminClient.setClientGroupDescription, and BrokerAdminClient.setClientInfosetById createClientQueueBrowser

BrokerClientQueueBrowser createClientQueueBrowser(String client_id) throws BrokerException

webMethods Broker Administration Java API Programmers 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. Possible Exceptions
BrokerIncompatibleVersionException

Meaning An attempt was made to create a queue browser on a pre-6.5 Broker client, which does not support queue browsers. The client has been already destroyed. The specified client ID does not exist on the Broker. A client queue browser is already open on the client queue from the same session.

BrokerInvalidClientException BrokerUnknownClientIdException BrokerClientQueueBrowserException

See Also: BrokerAdminClient.createLockedClientQueueBrowser and BrokerAdminClient.getClientQueueBrowsers createClientSubscriptionById

void createClientSubscriptionById( String client_id, BrokerSubscription sub) throws BrokerException

client_id sub

The identifier of the Broker client for which the subscription is to be created. The subscription to register for the Broker client, which specifies an event type name and a filter.

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

190

webMethods Broker Administration Java API Programmers Guide Version 8.2

12 Java API Administration Reference

Possible Exceptions
BrokerInvalidClientException BrokerInvalidSubscriptionException BrokerNoPermissionException

Meaning The BrokerAdminClient has been destroyed or disconnected. The filter string in sub contains a parse error. 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. The client_id, sub, or sub.event_type_name parameter is null. The specified client does not exist on the Broker. The event type does not exist on the Broker.

BrokerNullParameterException BrokerUnknownClientIdException BrokerUnknownEventTypeException

See Also: BrokerAdminClient.createClientSubscriptionsById, BrokerAdminClient.destroyClientSubscriptionById, BrokerAdminClient.destroyClientSubscriptionsById, BrokerAdminClient.doesClientSubscriptionExistById, and BrokerAdminClient.getClientSubscriptionsById createClientSubscriptionsById

void createClientSubscriptionsById( String client_id, BrokerSubscription subs[]) throws BrokerException

client_id subs

The identifier of the Broker client for which the subscription is to be created. The array of subscriptions to register for the Broker client, with each element specifying an event type name and a filter.

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

webMethods Broker Administration Java API Programmers Guide Version 8.2

191

12 Java API Administration Reference

getClientIdsByClientGroup getClientIdsWhichAreSubscribed Possible Exceptions

BrokerInvalidClientException BrokerInvalidSubscriptionException

Meaning The BrokerAdminClient has been destroyed or disconnected. One or more of the filter strings in subs contains a parse error. All correctly formatted subscriptions are still registered. 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. The parameter client_id, subs, a member of the subs array, or the event_type_name within a subscription is null. One of the elements in subs has a sub_id that is less that zero. The specified client does not exist on Broker. The event type does not exist on the Broker.

BrokerNoPermissionException

BrokerNullParameterException

BrokerOutOfRangeException BrokerUnknownClientIdException BrokerUnknownEventTypeException

See Also: BrokerAdminClient.createClientSubscriptionById, BrokerAdminClient.destroyClientSubscriptionById, BrokerAdminClient.destroyClientSubscriptionsById, BrokerAdminClient.doesClientSubscriptionExistById, and BrokerAdminClient.getClientSubscriptionsById createCluster

void createCluster( String cluster_name) throws BrokerException

cluster_name

The name of the cluster to be created. See the webMethods Broker Client Java API Programmers Guide for details on cluster name restrictions.

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
BrokerInClusterException

Meaning The Broker is already a member of the specified cluster.

192

webMethods Broker Administration Java API Programmers Guide Version 8.2

12 Java API Administration Reference

Possible Exceptions
BrokerInvalidClientException BrokerInvalidClusterNameException BrokerNoPermissionException

Meaning The BrokerAdminClient has been destroyed or disconnected. The cluster name specified is not valid. The BrokerAdminClient does not have permission to modify the Broker's properties or the Broker is not licensed for Broker interconnection. The cluster_name parameter is null.

BrokerNullParameterException

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

cluster_name broker_host

The name of the cluster to which this gateway is being created. 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. The name of the remote Broker that will act as the other end of the cluster gateway. The cluster gateway connection will be made primary if set to true.

broker_name isPrimary

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. Possible Exceptions
BrokerHostNotFoundException

Meaning The specified broker_host does not exist.

webMethods Broker Administration Java API Programmers Guide Version 8.2

193

12 Java API Administration Reference

Possible Exceptions
BrokerInvalidClientException BrokerNoPermissionException

Meaning The BrokerAdminClient has been destroyed or disconnected. The BrokerAdminClient does not have permission to modify the Broker's properties or the Broker is not licensed for Broker interconnection. The Broker is not a member of a cluster. A Broker Server could not be found on the broker_host. The cluster_name, broker_host, or broker_name is null. 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. If the specified Broker does not exist. There is no gateway to the specified cluster from this Broker.

BrokerNotInClusterException BrokerNotRunningException BrokerNullParameterException BrokerOutOfRangeException

BrokerUnknownBrokerNameException BrokerUnknownClusterException

See Also: BrokerAdminClient.createCluster and BrokerAdminClient.destroyClusterGateway. createForwardQueueBrowser

BrokerQueueBrowser createForwardQueueBrowser(java.lang.String remoteBroker) throws BrokerException

remoteBroker

Name of the remote Broker whose forward queue browser you want to create.

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. Possible Exceptions
BrokerInvalidClientException BrokerUnknownClientIdException

Meaning The forwarding queue has been already destroyed or is disconnected. The forwarding queue for the remote Broker specified does not exist on Broker.

194

webMethods Broker Administration Java API Programmers 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. Possible Exceptions
BrokerIncompatibleVersionException

Meaning An attempt was made to create a queue browser on a pre-6.5 Broker client, which does not support queue browsers. The client has been already destroyed. The specified client ID does not exist on the Broker. A client queue browser is already open on the client queue from the same session.

BrokerInvalidClientException BrokerUnknownClientIdException BrokerClientQueueBrowserException

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
BrokerIncompatibleVersionException

Meaning An attempt was made to create a queue browser on a pre-8.1 Broker Server, which does not support forwarding queue browsers. The client has been already destroyed or is disconnected.

BrokerInvalidClientException

webMethods Broker Administration Java API Programmers Guide Version 8.2

195

12 Java API Administration Reference

Possible Exceptions
BrokerQueueBrowserException BrokerQueueBrowserException

Meaning The forwarding queue for the remote Broker specified does not exist on Broker. A queue browser is already open on the forwarding queue from the same session.

See Also: BrokerAdminClient.createForwardQueueBrowser. createTerritory

void createTerritory( String territory_name) throws BrokerException

territory_name

The name of the territory name to be created. See the webMethods Broker Client Java API Programmers Guide for details on territory name restrictions.

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. Possible Exceptions
BrokerInTerritoryException BrokerInvalidClientException BrokerInvalidTerritoryNameException BrokerNoPermissionException

Meaning The Broker is already a member of the specified territory. The BrokerAdminClient has been destroyed or disconnected. The territory name specified is not valid. The BrokerAdminClient does not have permission to modify the Broker's properties or the Broker is not licensed for Broker interconnection. The parameter territory_name is null. If the territory requires SSL and the joining Broker does not support SSL.

BrokerNullParameterException BrokerSecurityException

See Also: BrokerAdminClient.createTerritoryGateway, BrokerAdminClient.getBrokersInTerritory, BrokerAdminClient.getTerritoryStats, BrokerAdminClient.joinTerritory, BrokerAdminClient.leaveTerritory, BrokerAdminClient.removeBrokerFromTerritory, BrokerAdminClient.setClientGroupACL, and BrokerAdminClient.setEventTypesAndClientGroups

196

webMethods Broker Administration Java API Programmers Guide Version 8.2

12 Java API Administration Reference

createTerritoryGateway
void createTerritoryGateway( String territory_name, String broker_host, String broker_name) throws BrokerException

territory_name broker_host

The name of the territory to which this gateway is being created. 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. The name of the remote Broker that will act as the other end of the gateway.

broker_name

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. Possible Exceptions
BrokerHostNotFoundException BrokerInvalidClientException BrokerNoPermissionException

Meaning The specified broker_host does not exist. The BrokerAdminClient has been destroyed or disconnected. The BrokerAdminClient does not have permission to modify the Broker's properties or the Broker is not licensed for Broker interconnection. The Broker is not a member of a territory. A Broker Server could not be found on the broker_host. The territory_name, broker_host, or broker_name is null. The territory_name is already connected to the territory of broker_host through some other gateway. There is no gateway to the specified territory from this Broker.

BrokerNotInTerritoryException BrokerNotRunningException BrokerNullParameterException BrokerOutOfRangeException

BrokerUnknownTerritoryException

See Also: BrokerAdminClient.createTerritory and BrokerAdminClient.destroyTerritoryGateway

webMethods Broker Administration Java API Programmers Guide Version 8.2

197

12 Java API Administration Reference

delete Method
deleteLogEvents
int deleteLogEvents( int from_index, int num_events) throws BrokerException

from_index num_events

events to be deleted starting from this index number of events to be deleted

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. Possible Exceptions
BrokerInvalidClientException BrokerNullParameterException BrokerOutOfRangeException

Meaning The BrokerAdminClient has been destroyed or disconnected. Events are null. Index is less than zero.

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. Possible Exceptions
BrokerInTerritoryException

Meaning The Broker is in a territory with at least one other Broker and must leave the territory before being destroyed. The BrokerServerClient has been destroyed or disconnected. Client does not have permission to destroy the Broker.

BrokerInvalidClientException BrokerNoPermissionException

See Also: BrokerServerClient.destroy

198

webMethods Broker Administration Java API Programmers Guide Version 8.2

12 Java API Administration Reference

destroyClientById
void destroyClientById( String client_id) throws BrokerException

client_id

The identifier of the Broker client to be destroyed.

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 Possible Exceptions
BrokerInvalidClientException BrokerNoPermissionException BrokerNullParameterException BrokerUnknownClientIdException

Meaning The BrokerAdminClient has been destroyed or disconnected. The BrokerAdminClient does not have permission to destroy the specified Broker client. The parameter client_id is null. The specified client does not exist on the Broker.

See Also: BrokerAdminClient.BrokerAdminClient, BrokerAdminClient.disconnectClientById, BrokerAdminClient.disconnectClientSessionById, BrokerClient.destroy, and BrokerClient.disconnect destroyClientGroup

void destroyClientGroup( String client_group_name, boolean reserved1) throws BrokerException

client_group_name reserved1

The name of the client group to be destroyed. Reserved for future. Must be set to false.

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.

webMethods Broker Administration Java API Programmers Guide Version 8.2

199

12 Java API Administration Reference

Possible Exceptions
BrokerDependencyException BrokerInvalidClientException BrokerNoPermissionException BrokerNullParameterException BrokerUnknownClientGroupException

Meaning One or more Broker clients are members of the client group. The BrokerAdminClient has been destroyed or disconnected. The BrokerAdminClient does not have permission to destroy the client group. The parameter client_group_name is null. The specified client group does not exist on the Broker.

See Also: BrokerAdminClient.createClientGroup, BrokerAdminClient.getClientGroupNames, and BrokerAdminClient.getClientIdsByClientGroup destroyClientSubscriptionById

void destroyClientSubscriptionById( String client_id, BrokerSubscription sub) throws BrokerException

client_id sub

The identifier of the Broker client for which the subscription is to be cancelled. 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.

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

Meaning The BrokerAdminClient has been destroyed or disconnected. There is no matching subscription for the specified Broker client.

200

webMethods Broker Administration Java API Programmers Guide Version 8.2

12 Java API Administration Reference

Possible Exceptions
BrokerNoPermissionException

Meaning The BrokerAdminClient does not have permission to modify the Broker client's subscription list. The client_id, sub, or sub.event_type_name parameter is null. The specified client does not exist on the Broker.

BrokerNullParameterException BrokerUnknownClientIdException

See Also: BrokerAdminClient.createClientSubscriptionById, BrokerAdminClient.createClientSubscriptionsById, BrokerAdminClient.destroyClientSubscriptionsById, BrokerAdminClient.doesClientSubscriptionExistById, and BrokerAdminClient.getClientSubscriptionsById destroyClientSubscriptionsById

void destroyClientSubscriptionsById( String client_id, BrokerSubscription subs[]) throws BrokerException

client_id subs

The identifier of the Broker client whose subscription are to be cancelled. 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.

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 Possible Exceptions
BrokerInvalidClientException

Meaning The BrokerAdminClient has been destroyed or disconnected.

webMethods Broker Administration Java API Programmers Guide Version 8.2

201

12 Java API Administration Reference

Possible Exceptions
BrokerInvalidSubscriptionException

Meaning 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. The BrokerAdminClient does not have permission to modify the Broker client's subscription list. The client_id or subs, parameter is null, any element in subs is null, or any element's event_type_name field is null. The specified client does not exist on the Broker.

BrokerNoPermissionException

BrokerNullParameterException

BrokerUnknownClientIdException

See Also: BrokerAdminClient.createClientSubscriptionById, BrokerAdminClient.createClientSubscriptionsById, BrokerAdminClient.destroyClientSubscriptionById, BrokerAdminClient.doesClientSubscriptionExistById, and BrokerAdminClient.getClientSubscriptionsById destroyClusterGateway

void destroyClusterGateway( String cluster_name, String broker_name) throws BrokerException

cluster_name broker_name

The name of the cluster whose gateway is to be destroyed. The name of the Broker belonging to the specified cluster to which the gateway is to be destroyed.

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. Possible Exceptions
BrokerInvalidClientException BrokerNoPermissionException BrokerNotInClusterException

Meaning The BrokerAdminClient has been destroyed or disconnected. The BrokerAdminClient does not have permission to modify the Broker's properties. The Broker is not a member of a cluster.

202

webMethods Broker Administration Java API Programmers Guide Version 8.2

12 Java API Administration Reference

Possible Exceptions
BrokerNullParameterException BrokerUnknownClusterException

Meaning The cluster_name or broker_name parameter value is null. There is no gateway connection to the specified cluster from this Broker.

See Also: BrokerAdminClient.createCluster and BrokerAdminClient.createClusterGateway destroyEventType

void destroyEventType( String event_type_name, boolean reserved1) throws BrokerException

event_type_name reserved1

The name of the event type to be destroyed. Reserved for future. Must be set to false.

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 Possible Exceptions
BrokerDependencyException

Meaning 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. The BrokerAdminClient has been destroyed or disconnected. The BrokerAdminClient does not have permission to destroy the event type. The parameter event_type_name is null. The event type does not exist on the Broker.

BrokerInvalidClientException BrokerNoPermissionException BrokerNullParameterException BrokerUnknownEventTypeException

webMethods Broker Administration Java API Programmers 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

event_type_name infoset_name

The name of the event type whose specified infoset is to be destroyed. The name of the infoset to be destroyed.

Destroys the specified infoset for the specified event type. Possible Exceptions
BrokerInvalidClientException BrokerNoPermissionException BrokerNullParameterException BrokerUnknownEventTypeException BrokerUnknownInfosetException

Meaning The BrokerAdminClient has been destroyed or disconnected. The BrokerAdminClient does not have permission to destroy the event type infoset. The parameter event_type_name or infoset_name is null. The event type does not exist on the Broker. The infoset does not exist on the Broker.

See Also: BrokerAdminClient.destroyEventTypeInfosets, BrokerAdminClient.setEventTypeInfoset, BrokerAdminClient.setEventTypeInfosets as well as BrokerClient.getEventTypeInfoset, and BrokerClient.getEventTypeInfosets (described in the webMethods Broker Client Java API Programmers Guide) destroyEventTypeInfosets
void destroyEventTypeInfosets( String event_type_name, String infoset_names[]) throws BrokerException

event_type_name infoset_names

The name of the event type whose specified infosets are to be destroyed. The names of the infosets to be destroyed.

204

webMethods Broker Administration Java API Programmers 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. Possible Exceptions
BrokerInvalidClientException BrokerNoPermissionException BrokerNullParameterException BrokerUnknownEventTypeException

Meaning The BrokerAdminClient has been destroyed or disconnected. The BrokerAdminClient does not have permission to destroy the event type infoset. The parameter event_type_name or any entry in infoset_names is null. The event type does not exist on the Broker.

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

event_type_names force_destroy

An array of names of the event types to be destroyed. If set to true, any Broker client subscriptions using any of the event types are destroyed as are any can-publish or cansubscribe 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.

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

webMethods Broker Administration Java API Programmers Guide Version 8.2

205

12 Java API Administration Reference

getClientGroupsWhichCanSubscribe Possible Exceptions

BrokerDependencyException

Meaning 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. The BrokerAdminClient has been destroyed or disconnected. The BrokerAdminClient does not have permission to destroy the event types. The parameter event_type_names is null or any of its elements is null.

BrokerInvalidClientException BrokerNoPermissionException BrokerNullParameterException

See Also: BrokerAdminClient.destroyEventTypeInfosets, BrokerAdminClient.setEventTypeInfoset, BrokerAdminClient.setEventTypeInfosets, BrokerClient.getEventTypeInfoset, and BrokerClient.getEventTypeInfosets destroyTerritoryGateway

void destroyTerritoryGateway( String territory_name) throws BrokerException

territory_name

The name of the territory whose gateway is to be destroyed.

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
BrokerInvalidClientException BrokerNoPermissionException BrokerNotInTerritoryException BrokerNullParameterException BrokerUnknownTerritoryException

Meaning The BrokerAdminClient has been destroyed or disconnected. The BrokerAdminClient does not have permission to modify the Broker's properties. The Broker is not a member of a territory. The territory_name parameter is null. There is no gateway to the specified territory from this Broker.

206

webMethods Broker Administration Java API Programmers 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

client_id

The identifier of the Broker client to be disconnected.

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 Possible Exceptions
BrokerInvalidClientException BrokerNoPermissionException BrokerNullParameterException BrokerUnknownClientIdException

Meaning The BrokerAdminClient has been destroyed or disconnected. The BrokerAdminClient does not have permission to disconnect the Broker client. The parameter client_id is null. The specified client does not exist on the Broker.

See Also: BrokerAdminClient.destroyClientById and BrokerAdminClient.disconnectClientSessionById

webMethods Broker Administration Java API Programmers Guide Version 8.2

207

12 Java API Administration Reference

disconnectClientSessionById
void disconnectClientSessionById( String client_id, int session_id) throws BrokerException

client_id session_id

The identifier of the Broker client. The identifier of the session to be disconnected.

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 Possible Exceptions
BrokerInvalidClientException BrokerNoPermissionException BrokerNullParameterException BrokerUnknownClientIdException BrokerUnknownSessionIdException

Meaning The BrokerAdminClient has been destroyed or disconnected. The BrokerAdminClient does not have permission to disconnect the Broker client. The client_id parameter is null. The specified client does not exist on the Broker. The specified client session does not exist on the Broker.

See Also: BrokerAdminClient.destroyClientById

does Method
doesClientSubscriptionExistById
boolean doesClientSubscriptionExistById( String client_id, String event_type_name, String filter) throws BrokerException

208

webMethods Broker Administration Java API Programmers Guide Version 8.2

12 Java API Administration Reference

client_id event_type_name filter

The identifier of the Broker client whose subscription is being tested. The event type name associated with the subscription being tested. The filter associated with the subscription being tested. This parameter can be set to null.

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 Possible Exceptions
BrokerInvalidClientException BrokerNoPermissionException BrokerNullParameterException BrokerUnknownClientIdException

Meaning The BrokerAdminClient has been destroyed or disconnected. The BrokerAdminClient does not have permission to read the Broker client's subscriptions. The client_id or event_type_name parameter is null. The specified client does not exist on the Broker.

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;

tx_id

The Broker transaction context to purge.

Forcibly purge a heuristic transaction.

webMethods Broker Administration Java API Programmers Guide Version 8.2

209

12 Java API Administration Reference

Exception
BrokerInvalidClientException BrokerInvalidTxException BrokerNoPermissionException

Description The BrokerAdminClient has been destroyed or disconnected. The transaction does not exist. The BrokerAdminClient does not have necessary permissions on the Broker.

forgetForced
void forgetForced(long tx_ids[]) throws BrokerException;

tx_ids

A list of Broker transaction contexts to purge.

Forcibly purge a list of heuristic transactions. Exception

BrokerInvalidClientException BrokerNullParameterException BrokerNoPermissionException

Description The BrokerAdminClient has been destroyed or disconnected. tx_ids is null. The BrokerAdminClient does not have necessary permissions on the Broker.

forgetForced
void forgetForced() throws BrokerException;

Forcibly purge all heuristic transactions. Exception

BrokerInvalidClientException BrokerNoPermissionException

Description The BrokerAdminClient has been destroyed or disconnected. The BrokerAdminClient does not have necessary permissions on the Broker.

get Methods
getActivityTraces
BrokerTraceEvent[] getActivityTraces( int seqn, int msecs) throws BrokerException

210

webMethods Broker Administration Java API Programmers Guide Version 8.2

12 Java API Administration Reference

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. The number of milliseconds this method will wait for trace information to be returned. If set to -1, it will block indefinitely.

msecs

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. Possible Exceptions
BrokerInterruptedException BrokerInvalidClientException BrokerNoPermissionException

Meaning This operation was interrupted before it could be completed. The BrokerAdminClient has been destroyed or disconnected. The BrokerAdminClient does not have permission to read the activity traces.

getAllClusterGateways
BrokerClusterGatewayInfo[] getAllClusterGateways() throws BrokerException

Returns all of the cluster gateways accessible from this Broker, through local gateways or gateways from other Brokers. Possible Exceptions
BrokerInvalidClientException BrokerNoPermissionException BrokerNotInClusterException

Meaning The BrokerAdminClient has been destroyed or disconnected. The BrokerAdminClient does not have permission to browse the Broker. The Broker is not a member of a cluster.

getAllQueueStats
public BrokerAllQueueStat[] getAllQueueStats() throws BrokerException

Returns a BrokerEvent object containing statistics for all clients.

webMethods Broker Administration Java API Programmers 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
now createTime numEventsPublished numEventsForwarded numEventsDelivered numEventsReceived numEventsQueued numEventsEnqueued numEventsRetrieved lastEventPublishTime

Type
BrokerDate BrokerDate int int int int int int int BrokerDate

Description Current time on the Broker host. Time when the client was created. Number of events published by this client. Number of events forwarded by the forwarding queue for the remote Broker. Number of events delivered by this client. Number of events received by the forwarding queue for the remote Broker. Number of events queued for this client. Number of events enqueued for the forwarding queue. Number of events retrieved by this client. 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. 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. 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. 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. 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. 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.

lastEventForwardTime

BrokerDate

lastEventDeliveryTime

BrokerDate

lastEventReceiveTime

BrokerDate

lastEventQueueTime

BrokerDate

lastEventRetrieveTime

BrokerDate

212

webMethods Broker Administration Java API Programmers Guide Version 8.2

12 Java API Administration Reference

Field Name
lastConnectTime lastConnectSession lastDisconnectTime lastDisconnectSession queueLength queueByteSize queueHighestLength queueHighestLengthTime

Type
BrokerDate int BrokerDate int long long long BrokerDate

Description Time when last session connected. Session ID of the last connected session. Time when last session disconnected. Session ID of the last disconnected session. Number of events in client queue. Number of bytes worth of events in client queue. Highest value of queueLength. Time when queueHighestLength was last set. A date and time value of zero indicates that the queueHighestLength has never been set.

Possible Exceptions
BrokerInvalidClientException BrokerNoPermissionException BrokerNotInClusterException

Meaning The BrokerAdminClient has been destroyed or disconnected. The BrokerAdminClient does not have permission to browse the Broker. The Broker is not a member of a cluster.

getAllTerritoryGateways
BrokerTerritoryGatewayInfo[] getAllTerritoryGateways() throws BrokerException

Returns all of the territory gateways accessible from this Broker, through local gateways or gateways from other Brokers. Possible Exceptions
BrokerInvalidClientException BrokerNoPermissionException BrokerNotInTerritoryException

Meaning The BrokerAdminClient has been destroyed or disconnected. The BrokerAdminClient does not have permission to browse the Broker. The Broker is not a member of a territory.

getBrokerDescription
String getBrokerDescription() throws BrokerException

Returns a string containing a description of the Broker to which this BrokerAdminClient is connected.

webMethods Broker Administration Java API Programmers Guide Version 8.2

213

12 Java API Administration Reference

Possible Exceptions
BrokerInvalidClientException

Meaning The BrokerAdminClient has been destroyed or disconnected.

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. Possible Exceptions
BrokerInvalidClientException BrokerNoPermissionException BrokerNotInClusterException

Meaning The BrokerAdminClient has been destroyed or disconnected. The BrokerAdminClient does not have permission to read the Broker's properties. This Broker is not part of a cluster.

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
BrokerInvalidClientException BrokerNoPermissionException BrokerNotInTerritoryException

Meaning The BrokerAdminClient has been destroyed or disconnected. The BrokerAdminClient does not have permission to read the Broker's properties. This Broker is not part of a territory.

214

webMethods Broker Administration Java API Programmers 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
createTime eventLogLength now numClients

Type
BrokerDate long BrokerDate int

Description The time the Broker was created. The number of events in the Broker log. Current time on the Broker host. The number of clients on the Broker, including disconnected clients. The number of event types installed. The number of events delivered by all clients. The number of events published by all clients. The number of events placed in client queues. The number of trace events published by Broker. The maximum number of publishes. The maximum number of events. Next operation sequence number. The number of guaranteed events.

numEventTypes numEventsDelivered numEventPublished numEventsQueued numTracesPublished retryQueueMaxPublishes retryQueueMaxEvents retryQueueNextOpsSequenceNum retryQueueReservedGuaranteedEvents

int int int int int int int int int

webMethods Broker Administration Java API Programmers Guide Version 8.2

215

12 Java API Administration Reference

Field Name
retryQueueReservedGuaranteedPublishes retryQueueReservedTotalPublishes retryQueueReservedVolatileEvents retryQueueReservedVolatilePublishes retryQueueCurrentEvents retryQueueCurrentPublishes traceLastEventEnqueueTime traceNumEventsQueued traceQueueByteSize traceQueueHighestLength traceQueueHighestLengthTime

Type
int int int int int int date int long long date

Description The number of guaranteed publishes. The total number of reserved publishes. The number of volatile events. The number of volatile publishes. The number of current events. The number of current publishes. The time when last event was enqueued. The number of events placed in the queue. The number of bytes worth of events in the queue. The highest value of traceQueueLength. 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
BrokerInvalidClientException BrokerNoPermissionException

Meaning The BrokerAdminClient has been destroyed or disconnected. The BrokerAdminClient does not have permission to read the Broker's statistics.

See Also: BrokerAdminClient.getClientGroupStats, BrokerAdminClient.getClientStatsById, and BrokerAdminClient.getEventTypeStats

216

webMethods Broker Administration Java API Programmers Guide Version 8.2

12 Java API Administration Reference

getClientGroupACL
BrokerAccessControlList getClientGroupACL( String client_group_name) throws BrokerException

client_group_name

The name of the client group whose access control list is to be returned.

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. Possible Exceptions
BrokerInvalidClientException BrokerNoPermissionException BrokerNullParameterException BrokerUnknownClientGroupException

Meaning The BrokerAdminClient has been destroyed or disconnected. The BrokerAdminClient does not have permission to read the client group's Access Control List. The client_group_name parameter is null. The specified client_group_name does not exist on the Broker.

See Also: BrokerAdminClient.setClientGroupACL getClientGroupCanPublishList

String[] getClientGroupCanPublishList( String client_group_name) throws BrokerException

client_group_name

The name of the client group whose publish list is to be returned.

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. Possible Exceptions
BrokerInvalidClientException BrokerNoPermissionException BrokerNullParameterException BrokerUnknownClientGroupException

Meaning The BrokerAdminClient has been destroyed or disconnected. The BrokerAdminClient does not have permission to read the client group's can-publish list. The client_group_name parameter is null. The specified client_group_name does not exist on the Broker.

webMethods Broker Administration Java API Programmers 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

client_group_name

The name of the client group whose subscribe list is to be returned.

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. Possible Exceptions
BrokerInvalidClientException BrokerNoPermissionException BrokerNullParameterException BrokerUnknownClientGroupException

Meaning The BrokerAdminClient has been destroyed or disconnected. The BrokerAdminClient does not have permission to read the client group's can-subscribe list. The client_group_name parameter is null. The specified client_group_name does not exist on the Broker.

See Also: BrokerAdminClient.getClientGroupCanPublishList, BrokerAdminClient.setClientGroupCanPublishList, and BrokerAdminClient.setClientGroupCanSubscribeList getClientGroupInfo

BrokerClientGroupInfo getClientGroupInfo( String client_group_name) throws BrokerException

client_group_name

The name of the client group whose information is to be returned.

Returns the client group's information. See BrokerClientGroupInfo for more information on the format of the returned object. Possible Exceptions
BrokerInvalidClientException

Meaning The BrokerAdminClient has been destroyed or disconnected.

218

webMethods Broker Administration Java API Programmers Guide Version 8.2

12 Java API Administration Reference

Possible Exceptions
BrokerNoPermissionException BrokerNullParameterException BrokerUnknownClientGroupException

Meaning The BrokerAdminClient does not have permission to read the client group's information. The client_group_name parameter is null. The specified client_group_name does not exist on the Broker.

See Also: BrokerAdminClient.getClientGroupInfos and BrokerAdminClient.getClientGroupNames getClientGroupInfos

BrokerClientGroupInfo[] getClientGroupInfos( String client_group_names[]) throws BrokerException

client_group_names

An array of names of the client groups whose information is to be returned.

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. Possible Exceptions
BrokerInvalidClientException BrokerNullParameterException

Meaning The BrokerAdminClient has been destroyed or disconnected. An entry in the client_group_names parameter is null.

See Also: BrokerAdminClient.getClientGroupInfo, BrokerAdminClient.getClientGroupNames getClientGroupLogAcknowledgeList

java.lang.String[]getClientGroupLogAcknowledgeList( java.lang.String client_group_name) throws BrokerException

client_group_name

The name of the client group whose event types are to be logged.

Get the list of event types that are logged when they are acknowledged by a client in the the specified client group.

webMethods Broker Administration Java API Programmers Guide Version 8.2

219

12 Java API Administration Reference

Possible Exceptions
BrokerInvalidClientException BrokerNoPermissionException BrokerNullParameterException BrokerUnknownClientGroupException

Meaning The BrokerAdminClient has been destroyed or disconnected. The BrokerAdminClient does not have permission to browse the client group's information. The client_group_name parameter is null. The specified client_group_name does not exist on the Broker.

getClientGroupLogPublishList
java.lang.String[]getClientGroupLogPublishList( java.lang.String client_group_name) throws BrokerException

client_group_name

The name of the client group whose event types are to be logged.

Get the list of event types that are logged when published or delivered by a client in the specified client group. Possible Exceptions
BrokerInvalidClientException BrokerNoPermissionException BrokerNullParameterException BrokerUnknownClientGroupException

Meaning The BrokerAdminClient has been destroyed or disconnected. The BrokerAdminClient does not have permission to browse the client group's information. The client_group_name parameter is null. The specified client_group_name does not exist on the Broker.

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. Possible Exceptions
BrokerInvalidClientException

Meaning The BrokerAdminClient has been destroyed or disconnected.

See Also: BrokerAdminClient.getClientGroupInfo and BrokerAdminClient.getClientGroupInfos

220

webMethods Broker Administration Java API Programmers Guide Version 8.2

12 Java API Administration Reference

getClientGroupStats
BrokerEvent getClientGroupStats( String client_group_name) throws BrokerException

client_group_name

The name of the client group whose statistics are to be returned.

Returns a BrokerEvent object containing statistics for the specified client group. The following table shows the events returned by the BrokerAdminClient.getClientGroupStats method. Field Name
now createTime numEventsDelivered numEventsPublished lastEventDeliveryTime lastEventPublishTime lastUpdateTime

Type
BrokerDate BrokerDate int int BrokerDate BrokerDate BrokerDate

Description Current time on the Broker host. The time the client group was created. The number of events delivered by all clients in this group. The number of events published by all clients in this group. Time when an event was last delivered by a client in this group. Time when an event was last published by a client in this group. Time when this group was last updated. Meaning The BrokerAdminClient has been destroyed or disconnected. The BrokerAdminClient does not have permission to get the client group's statistics. The client_group_name parameter is null. The specified client_group_name does not exist on the Broker.

Possible Exceptions
BrokerInvalidClientException BrokerNoPermissionException BrokerNullParameterException BrokerUnknownClientGroupException

See Also: BrokerAdminClient.getBrokerStats, BrokerAdminClient.getClientStatsById, and BrokerAdminClient.getEventTypeStats getClientGroupsWhichCanPublish

String[] getClientGroupsWhichCanPublish( String event_type_name) throws BrokerException

webMethods Broker Administration Java API Programmers Guide Version 8.2

221

12 Java API Administration Reference

event_type_name

The name of the event type.

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. Possible Exceptions
BrokerInvalidClientException BrokerNullParameterException BrokerUnknownEventTypeException

Meaning The BrokerAdminClient has been destroyed or disconnected. The event_type_name parameter is null. The specified event_type_name does not exist on the Broker.

See Also: BrokerAdminClient.getClientGroupsWhichCanPublish and BrokerAdminClient.setClientGroupCanPublishList getClientGroupsWhichCanSubscribe

String[] getClientGroupsWhichCanSubscribe( String event_type_name) throws BrokerException

event_type_name

The name of the event type.

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. Possible Exceptions
BrokerInvalidClientException BrokerNullParameterException BrokerUnknownEventTypeException

Meaning The BrokerAdminClient has been destroyed or disconnected. The event_type_name parameter is null. The specified event_type_name does not exist on the Broker.

222

webMethods Broker Administration Java API Programmers 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. Possible Exceptions
BrokerInvalidClientException

Meaning The BrokerAdminClient has been destroyed or disconnected.

See Also: BrokerAdminClient.getClientIdsByClientGroup and BrokerAdminClient.getClientIdsWhichAreSubscribed getClientIdsByClientGroup

String[] getClientIdsByClientGroup( String client_group_name) throws BrokerException

client_group_name

The name of the client group whose member client identifier list is to be returned.

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. Possible Exceptions
BrokerInvalidClientException BrokerNoPermissionException BrokerNullParameterException BrokerUnknownClientGroupException

Meaning The BrokerAdminClient has been destroyed or disconnected. The BrokerAdminClient does not have permission to get the list of client identifiers. The client_group_name parameter is null. The specified client_group_name does not exist on the Broker.

See Also: BrokerAdminClient.getClientIds and BrokerAdminClient.getClientIdsWhichAreSubscribed

webMethods Broker Administration Java API Programmers Guide Version 8.2

223

12 Java API Administration Reference

getClientIdsWhichAreSubscribed
String[] getClientIdsWhichAreSubscribed( String event_type_name) throws BrokerException

event_type_name

The name of the event type.

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. Possible Exceptions
BrokerInvalidClientException BrokerNullParameterException BrokerUnknownEventTypeException

Meaning The BrokerAdminClient has been destroyed or disconnected. The event_type_name parameter is null. The specified event_type_name does not exist on the Broker.

See Also:
BrokerAdminClient.getClientIds

and BrokerAdminClient.getClientIdsByClientGroup

getClientInfoById
BrokerClientInfo getClientInfoById( String client_id) throws BrokerException

client_id

The identifier of the client whose information is to be returned.

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 Possible Exceptions
BrokerInvalidClientException BrokerNoPermissionException BrokerNullParameterException BrokerUnknownClientIdException

Meaning The BrokerAdminClient has been destroyed or disconnected. The BrokerAdminClient does not have permission to get the client information. The client_id parameter is null. The specified client_id does not exist on the Broker.

224

webMethods Broker Administration Java API Programmers Guide Version 8.2

12 Java API Administration Reference

See Also: BrokerAdminClient.getClientInfosById getClientInfosById

BrokerClientInfo[] getClientInfosById( String client_ids[]) throws BrokerException

client_ids

An array of identifiers for the clients whose information is to be returned.

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 Possible Exceptions
BrokerInvalidClientException BrokerNullParameterException

Meaning The BrokerAdminClient has been destroyed or disconnected. An entry in the client_ids array is null.

See Also: BrokerAdminClient.getClientInfoById getClientInfosetById

BrokerEvent getClientInfosetById( String client_id) throws BrokerException

client_id

The identifier of the Broker client whose infoset is to be returned.

Returns the infoset for the Broker client with the specified client_id, which is returned as a BrokerEvent for convenience.

webMethods Broker Administration Java API Programmers Guide Version 8.2

225

12 Java API Administration Reference

Possible Exceptions
BrokerInvalidClientException BrokerNoPermissionException BrokerNullParameterException BrokerUnknownClientIdException

Meaning The BrokerAdminClient has been destroyed or disconnected. The BrokerAdminClient does not have permission to get the client infoset. The client_id parameter is null. The specified client_id does not exist on the Broker.

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. Possible Exceptions
BrokerIncompatibleVersionExcept ion BrokerInvalidClientException

Meaning An attempt was made to create a queue browser on a pre-6.5 Broker client, which does not support queue browsers. The client has been already destroyed.

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

client_id flags

Represents the id of the client whose queue will be locked. (0) Not yet implemented. Returns BrokerClientQueueLock object.

226

webMethods Broker Administration Java API Programmers 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

client_id

The identifier of the client whose statistics are to be returned.

Returns BrokerEvent containing statistics for the specified Broker client. The following table shows the events returned by the BrokerAdminClient.getClientStatsById method. Field Name
now createTime numEventsDelivered numEventsPublished numEventsRetrieved lastEventDeliveryTime

Type
BrokerDate BrokerDate int int int BrokerDate

Description Current time on the Broker host. The time the client was created. The number of events delivered by the client. The number of events published by the client. The number of events retrieved by the client. Time when an event was last delivered by a client in this group. A value of zero means no event has ever been delivered. Time when an event was last published by a client in this group. A value of zero means no event has ever been published. Time when an event was last placed in this client's queue. A value of zero means no event has ever been queued. Time when an event was last retrieved from the queue by a client. A value of zero means no event has ever been retrieved. Number of events in the client's queue. The number of bytes of events in the client's queue. Highest value of queue length, so far.

lastEventPublishTime

BrokerDate

lastEventQueueTime

BrokerDate

lastEventRetrieveTime

BrokerDate

queueLength queueByteSize queueHighestLength

long long long

webMethods Broker Administration Java API Programmers Guide Version 8.2

227

12 Java API Administration Reference

Field Name
queueHighestLengthTime

Type
BrokerDate

Description Time when queueHighestLength was last set. A value of zero means the client has never had an event queued.

You can obtain a list of client identifiers by invoking the one of the following methods: getClientIds getClientIdsByClientGroup getClientIdsWhichAreSubscribed Possible Exceptions
BrokerInvalidClientException BrokerNoPermissionException BrokerNullParameterException BrokerUnknownClientIdException

Meaning The BrokerAdminClient has been destroyed or disconnected. The BrokerAdminClient does not have permission to get the client's statistics. The client_id parameter is null. The specified client_id does not exist on the Broker.

See Also: BrokerAdminClient.getBrokerStats, BrokerAdminClient.getClientGroupStats, and BrokerAdminClient.getEventTypeStats getClientSubscriptionsById

BrokerSubscription[] getClientSubscriptionsById( String client_id) throws BrokerException

client_id

The identifier of the client whose subscriptions are to be returned.

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

228

webMethods Broker Administration Java API Programmers Guide Version 8.2

12 Java API Administration Reference

Possible Exceptions
BrokerInvalidClientException BrokerNoPermissionException BrokerNullParameterException BrokerUnknownClientIdException

Meaning The BrokerAdminClient has been destroyed or disconnected. The BrokerAdminClient does not have permission to get the client's subscription list. The client_id parameter is null. The specified client_id does not exist on the Broker.

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. Possible Exceptions
BrokerInvalidClientException BrokerNoPermissionException BrokerNotInClusterException

Meaning The BrokerAdminClient has been destroyed or disconnected. The BrokerAdminClient does not have permission to browse the Broker. The Broker is not a member of a cluster.

See Also: BrokerAdminClient.setClusterACL getClusterGatewayACL

BrokerAccessControlList getClusterGatewayACL( String cluster_name) throws BrokerException

cluster_name

The name of the cluster whose gateway ACL is to be returned.

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.

webMethods Broker Administration Java API Programmers 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. Possible Exceptions
BrokerInvalidClientException BrokerNoPermissionException BrokerNotInClusterException BrokerNullParameterException BrokerUnknownClusterException

Meaning The BrokerAdminClient has been destroyed or disconnected. The BrokerAdminClient does not have permission to browse the Broker. The Broker is not a member of a cluster. The cluster_name parameter value is null. There is no gateway to the specified cluster from this client's Broker.

See Also: BrokerAdminClient.setClusterGatewayACL. getClusterGatewayKeepAlive

int getClusterGatewayKeepAlive( String cluster_name) throws BrokerException

cluster_name

The name of the cluster whose keep-alive status you want to check. Meaning The BrokerAdminClient has been destroyed or disconnected. The BrokerAdminClient does not have permission to browse the Broker. The Broker is not a member of a cluster. The cluster_name parameter value is null. There is no gateway to the specified cluster from this client's Broker.

Possible Exceptions
BrokerInvalidClientException BrokerNoPermissionException BrokerNotInClusterException BrokerNullParameterException BrokerUnknownClusterException

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.

230

webMethods Broker Administration Java API Programmers Guide Version 8.2

12 Java API Administration Reference

getClusterGatewayRefuseAllUpdates
boolean getClusterGatewayRefuseAllUpdates( String cluster_name) throws BrokerException

cluster_name

The name of the cluster to which the updates are accepted or refused.

Returns whether a cluster gateway refuses all the updates made in a connected cluster (true) or accepts all the updates (false). Possible Exceptions
BrokerInvalidClientException BrokerNoPermissionException BrokerNotInClusterException BrokerNullParameterException BrokerUnknownClusterException

Meaning The BrokerAdminClient has been destroyed or disconnected. The BrokerAdminClient does not have permission to browse the Broker. The Broker is not a member of a cluster. The cluster_name parameter is null. There is no gateway to the specified cluster from this client's Broker.

See Also: BrokerAdminClient.setClusterGatewayRefuseAllUpdates. getClusterGatewaySharedEventTypes

BrokerSharedEventTypeInfo[] getClusterGatewaySharedEventTypes( String cluster_name, String broker_name) throws BrokerException

cluster_name broker_name

The name of the cluster whose event types are shared. The name of the Broker in the specified cluster. This Broker is used to identify the right gateway link for information retrieval.

Gets the complete list of event types shared across a cluster gateway. See BrokerSharedEventTypeInfo for more information. Possible Exceptions
BrokerInvalidClientException BrokerNoPermissionException

Meaning The BrokerAdminClient has been destroyed or disconnected The client does not have permission to modify the Broker.

webMethods Broker Administration Java API Programmers Guide Version 8.2

231

12 Java API Administration Reference

Possible Exceptions
BrokerNotInClusterException BrokerNullParameterException BrokerUnknownClusterException

Meaning If the specified Broker is not a member of the specified cluster. The cluster_name or broker_name parameter value is null. There is no gateway connection to the specified cluster from this Broker.

See Also: BrokerAdminClient.setClusterGatewaySharedEventTypes. getClusterGatewayStats

BrokerEvent getClusterGatewayStats( String cluster_name, String broker_name) throws BrokerException

cluster_name broker_name

The name of the cluster whose gateway statistics are to be returned. The name of the Broker in the specified cluster. This Broker is used to identify the right gateway link for information retrieval.

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. Field Name
authProtocol

Type
unicode_string

Description 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". 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". The IP address of the remote Broker. Set to an empty string if the gateway is not connected.

authVersion

unicode_string

connectedFrom

unicode_string

232

webMethods Broker Administration Java API Programmers Guide Version 8.2

12 Java API Administration Reference

Field Name
encryptLevel

Type
unicode_string

Description The level of encryption being used. Only set if encryptProtocol is set. Currently supported values are "USDomestic" and "USExport". The encryption protocol being used. Only set if connectedFrom is not empty. The only values currently supported is "SSL". The version of the encryption protocol being used. Only set if encryptProtocol is not empty. Currently supported values are "2" and "3". 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. 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. The session id from which the gateway was paused. If outbound traffic is not currently paused for cluster_name, this parameter will be 0. The time when the gateway was paused. If outbound traffic is not currently paused for cluster_name, this parameter will be 0. The name of the gateway Broker. The name of the gateway Broker's host. The time the Broker was last connected. Set to zero if never connected. Time when an event was last enqueued for the gateway.

encryptProtocol

unicode_string

encryptVersion

unicode_string

gateway_pause

boolean

gateway_pause_client

String

gateway_pause_session

integer

gateway_pause_time

date

gatewayBrokerName gatewayHost lastConnectTime

unicode_string unicode_string Date

lastEventEnqueueTime

Date

webMethods Broker Administration Java API Programmers Guide Version 8.2

233

12 Java API Administration Reference

Field Name
lastEventForwardTime

Type
Date

Description Time when an event was last forwarded across the gateway. Set to zero if no events have been forwarded. Time when an event was last received across the gateway. Set to zero if no events have been received. Current time on the Broker host. Number of events that were forwarded across the gateway. The number of events received across the gateway. Number of events enqueued for the gateway. The current size, in bytes, of the gateway's queue. The highest number of events in the gateway's queue. Time when queueHighestLength was last changed. The number of events currently in the gateway's queue. The name of the cluster. The date of the Broker's certificate became valid. The serial number of the Broker's certificate. Set only if authProtocol is set to "SSL". The date the Broker's certificate expires. Set only if authProtocol is set to "SSL" The status of the other Broker's certificate. Set only if authProtocol is set to "SSL". The distinguished name s of the other Broker's certificate. Set only if authProtocol is set to "SSL".

lastEventReceiveTime

Date

now numEventsForwarded numEventsReceived numEventsEnqueued queueByteSize queueHighestLength queueHighestLengthTime queueLength remoteClusterName sslCertBeginDate sslCertSerialNumber

Date int int int int int BrokerDate int unicode_string Date unicode_string

sslCertEndDate

BrokerDate

sslCertStatus

unicode_string

sslDistinguishedName

unicode_string

234

webMethods Broker Administration Java API Programmers Guide Version 8.2

12 Java API Administration Reference

Field Name
sslIssuerDistinguishedName

Type
unicode_string

Description The distinguished name s of the issuer of the other Broker's certificate. Set only if authProtocol is set to "SSL".

Possible Exceptions
BrokerInvalidClientException BrokerNoPermissionException BrokerNotInClusterException BrokerNullParameterException BrokerUnknownClusterException

Meaning The BrokerAdminClient has been destroyed or disconnected. The BrokerAdminClient does not have permission to get the cluster statistics. This client's Broker is not part of a cluster. The cluster_name or broker_name parameter is null. There is no gateway to the specified cluster from this client's Broker.

See Also: BrokerAdminClient.addBrokerToCluster getClusterInfo

BrokerClusterInfo getClusterInfo() throws BrokerException

Returns a BrokerClusterInfo object that contains the cluster settings. Possible Exceptions
BrokerInvalidClientException BrokerNoPermissionException BrokerNotInClusterException

Meaning The BrokerAdminClient has been destroyed or disconnected. The BrokerAdminClient does not have permission to browse the Broker. This client's Broker is not a member of a cluster.

getClusterStaticGatewayForwarding
boolean getClusterStaticGatewayForwarding(String cluster_name) throws BrokerException

cluster_name

The name of the remote cluster.

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.

webMethods Broker Administration Java API Programmers Guide Version 8.2

235

12 Java API Administration Reference

Possible Exceptions
BrokerInvalidClientException BrokerNotInClusterException BrokerUnknownClusterException BrokerNullParameterException

Meaning The client is not valid. The gateway Broker is not in a cluster. On the current Broker, there is no local gateway to the specified remote cluster. The cluster_name is null.

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: Field Name
brokers

Type
structure[]

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

unicode_string

brokers.authVersion

unicode_string

236

webMethods Broker Administration Java API Programmers Guide Version 8.2

12 Java API Administration Reference

Field Name
brokers.brokerHost brokers.brokerName brokers.connectedFrom brokers.description brokers.encryptLevel

Type
unicode_string unicode_string boolean unicode_string unicode_string

Description The Broker host name. The Broker Server name. Set to true if the Broker is currently connected. The Broker's description. The level of encryption being used. Only set if encryptProtocol is set. Currently supported values are "USDomestic" and "USExport". The encryption protocol being used. Only set if connectedFrom is not empty. The only values currently supported is "SSL". The version of the encryption protocol being used. Only set if encryptProtocol is not empty. Currently supported values are "2" and "3". The time the Broker was last connected. Set to zero if never connected. The time an event was last enqueued for the Broker. Set to zero if no events have ever be enqueued. Time when an event of this type was last forwarded to the Broker. Set to zero if no events have been forwarded. Time when an event was last received by the Broker. Set to zero if no events have been received. Number of events that were enqueued for the Broker.

brokers.encryptProtocol

unicode_string

brokers.encryptVersion

unicode_string

brokers.lastConnectTime

BrokerDate

brokers.lastEventEnqueueTime

BrokerDate

brokers.lastEventForwardTime

BrokerDate

brokers.lastEventReceiveTime

BrokerDate

brokers.numEventsEnqueued

int

webMethods Broker Administration Java API Programmers Guide Version 8.2

237

12 Java API Administration Reference

Field Name
brokers.numEventsForwarded brokers.numEventsReceived brokers.queueByteSize brokers.queueHighestLength brokers.queueHighestLengthTime

Type
int int int int BrokerDate

Description Number of events that were forwarded to the Broker. The number of events received by the Broker. The current size, in bytes, of the Broker's queue. The highest number of events in the Broker's queue. Time when
queueHighestLength

was last

changed.
brokers.queueLength int

The number of events currently in the Broker's queue. The date of the Broker's certificate became valid. The serial number of the Broker's certificate. Set only if authProtocol is set to "SSL". The date the Broker's certificate expires. The status of the Broker's certificate. Set only if authProtocol is set to "SSL". The distinguished name s of the Broker's certificate. Set only if authProtocol is set to "SSL". The distinguished name s of the issuer of the other Broker's certificate. Set only if authProtocol is set to "SSL". Current time on the Broker host. The name of the cluster.

brokers.sslCertBeginDate brokers.sslCertSerialNumber

BrokerDate unicode_string

brokers.sslCertEndDate brokers.sslCertStatus

BrokerDate unicode_string

brokers.sslDistinguishedName

unicode_string

brokers.sslIssuerDistinguishedName

unicode_string

now clusterName

BrokerDate unicode_string

238

webMethods Broker Administration Java API Programmers Guide Version 8.2

12 Java API Administration Reference

getEventAdminTypeDef
BrokerAdminTypeDef getEventAdminTypeDef( String event_type_name) throws BrokerException

event_type_name

The name of the event type whose type definition information is to be returned.

Returns a BrokerAdminTypeDef object containing the type definition for the specified event type. Possible Exceptions
BrokerInvalidClientException BrokerNoPermissionException BrokerNullParameterException BrokerUnknownEventTypeException

Meaning The BrokerAdminClient has been destroyed or disconnected. The BrokerAdminClient does not have permission to read the event type definition. The event_type_name parameter is null. The specified event_type_name does not exist on the Broker.

See Also: BrokerAdminClient.destroyEventType, BrokerAdminClient.destroyEventTypes, BrokerAdminClient.getEventAdminTypeDef, BrokerAdminClient.getEventAdminTypeDefsByScope, BrokerAdminClient.setEventAdminTypeDef, and BrokerAdminClient.setEventAdminTypeDefs getEventAdminTypeDefs
BrokerAdminTypeDef[] getEventAdminTypeDefs( String event_type_names[]) throws BrokerException

event_type_names

An array containing the names of the event types whose type definition information are to be returned.

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.

webMethods Broker Administration Java API Programmers 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. Possible Exceptions
BrokerInvalidClientException BrokerNullParameterException

Meaning The BrokerAdminClient has been destroyed or disconnected. The event_type_names parameter, or any element in that array is null.

See Also: BrokerAdminClient.destroyEventType, BrokerAdminClient.destroyEventTypes, BrokerAdminClient.getEventAdminTypeDef, BrokerAdminClient.getEventAdminTypeDefsByScope, BrokerAdminClient.setEventAdminTypeDef, and BrokerAdminClient.setEventAdminTypeDefs getEventAdminTypeDefsByScope
BrokerAdminTypeDef[] getEventAdminTypeDefsByScope( String scope_name) throws BrokerException

scope_name

The name of the scope whose event type definitions are to be returned.

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. Possible Exceptions
BrokerInvalidClientException BrokerNullParameterException BrokerUnknownEventTypeException

Meaning The BrokerAdminClient has been destroyed or disconnected. The scope_name parameter is null. The scope does not exist on the Broker.

See Also: BrokerAdminClient.destroyEventType, BrokerAdminClient.destroyEventTypes, BrokerAdminClient.getEventAdminTypeDef, BrokerAdminClient.getEventAdminTypeDefs, BrokerAdminClient.setEventAdminTypeDef, and BrokerAdminClient.setEventAdminTypeDefs

240

webMethods Broker Administration Java API Programmers 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

event_type_name

The event type whose statistics are to be returned.

Returns a BrokerEvent containing statistics for the specified event type. The following table shows events returned by the BrokerAdminClient.getEventTypeStats method: Field Name
createTime lastEventDeliveryTime lastEventPublishTime lastForwardReceivedTime

Type
BrokerDate BrokerDate BrokerDate BrokerDate

Description The time the event type was created. Time when an event of this type was last delivered on this Broker. Time when an event of this type was last published on this Broker. Time when an event of this type was last forwarded to this Broker by another Broker. Current time on the Broker host. Number of open subscriptions which include this event type by Clients on this Broker. The number of events of this type that have been delivered on this Broker. The number of events of this type that have been published on this Broker. Number of events of this type that were forwarded to this Broker by another Broker. Number of client groups that can publish this event type.

now numClientSubscriptions

BrokerDate int

numEventsDelivered numEventsPublished numForwardsReceived

int int int

numGroupsCanPublish

int

webMethods Broker Administration Java API Programmers Guide Version 8.2

241

12 Java API Administration Reference

Field Name
numGroupsCanSubscribe updateTime

Type
int BrokerDate

Description Number of client groups that can subscribe to this event type. 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
BrokerInvalidClientException BrokerNoPermissionException BrokerNullParameterException BrokerUnknownEventTypeException

Meaning The BrokerAdminClient has been destroyed or disconnected. The BrokerAdminClient does not have permission to get the event's statistics. The event_type_name parameter is null. The specified event type does not exist on the Broker.

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. Field Name
now transactions transactions.transactionId transactions.externalId transactions.clientId transactions.sessionId transactions.state transactions.createdTime

Type
BrokerDate struct[] long UnicodeString UnicodeString int int BrokerDate

242

webMethods Broker Administration Java API Programmers Guide Version 8.2

12 Java API Administration Reference

Field Name
transactions.endedTime transactions.preparedTime transactions.closedTime transactions.closedReason transactions.unpreparedTimeout transactions.preparedTimeoutInterval transactions.preparedTimeout transactions.numEventsReceived transactions.numEventsAcknowledged transactions.numEventsPublished

Type
BrokerDate BrokerDate BrokerDate int BrokerDate int BrokerDate int int int

Possible Exceptions
BrokerInvalidClientException BrokerNoPermissionException

Meaning The BrokerAdminClient has been destroyed or disconnected. The BrokerAdminClient does not have permission to browse the Broker.

See Also: BrokerAdminClient.forgetForced getLocalClusterGateways

BrokerClusterGatewayInfo[] getLocalClusterGateways() throws BrokerException

Returns a list of clusters for which this Broker is acting as a gateway. Possible Exceptions
BrokerInvalidClientException BrokerNoPermissionException BrokerNotInClusterException

Meaning The BrokerAdminClient has been destroyed or disconnected. The BrokerAdminClient does not have permission to browse the Broker. The Broker is not a member of a cluster.

See Also: BrokerAdminClient.getAllClusterGateways

webMethods Broker Administration Java API Programmers 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. Possible Exceptions
BrokerInvalidClientException BrokerNoPermissionException BrokerNotInTerritoryException

Meaning The BrokerAdminClient has been destroyed or disconnected. The BrokerAdminClient does not have permission to browse the Broker. The Broker is not a member of a territory.

See Also: BrokerAdminClient.getAllTerritoryGateways getLogEvents

BrokerEvent[] getLogEvents( int from_index, int max_events, int msecs) throws BrokerException

from_index max_events msecs

Events to be logged starting from this index. Maximum number of events that may be logged.

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
BrokerInvalidClientException BrokerOutOfRangeException BrokerNullParameterException BrokerTimeoutException BrokerException

Meaning The BrokerAdminClient has been destroyed or disconnected. from_index is less than zero. max_events, msecs equals zero. Reply from Broker is null. XcellpadX

244

webMethods Broker Administration Java API Programmers Guide Version 8.2

12 Java API Administration Reference

getLogLength
int getLogLength() throws BrokerException

Returns the number of events in the Broker's log. Possible Exceptions

BrokerInvalidClientException

Meaning The client is not valid. In addition, any of the communications errors can occur.

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. Possible Exceptions
BrokerInvalidClientException BrokerNoPermissionException BrokerIncompatibleVersionException

Meaning The BrokerAdminClient has been destroyed or disconnected. The BrokerAdminClient does not have permission to browse the Broker. The Broker does not support transaction administration.

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
BrokerInvalidClientException BrokerNoPermissionException BrokerIncompatibleVersionException

Meaning The BrokerAdminClient has been destroyed or disconnected. The BrokerAdminClient does not have permission to browse the Broker. The Broker does not support transaction administration.

webMethods Broker Administration Java API Programmers 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. Possible Exceptions
BrokerInvalidClientException BrokerNoPermissionException BrokerIncompatibleVersionException

Meaning The BrokerAdminClient has been destroyed or disconnected. The BrokerAdminClient does not have permission to browse the Broker. The Broker does not support transaction administration.

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). Possible Exceptions
BrokerInvalidClientException BrokerNoPermissionException

Meaning The BrokerAdminClient has been destroyed or disconnected. The BrokerAdminClient does not have permission to browse the Broker.

See Also: BrokerAdminClient.setRecoverMode getRemoteBrokerKeepAlive

void getRemoteBrokerKeepAlive( String broker_name) throws BrokerException

246

webMethods Broker Administration Java API Programmers Guide Version 8.2

12 Java API Administration Reference

broker_name

The name of the Broker whose keep-alive status you want to check. Meaning The BrokerAdminClient has been destroyed or disconnected territory_name is null

Possible Exceptions
BrokerInvalidClientException BrokerNullParameterException

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

territory_name

name of the remote territory

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. Possible Exceptions
BrokerInvalidClientException BrokerNotInTerritoryException BrokerUnknownTerritoryException BrokerNullParameterException

Meaning The client is not valid. The gateway Broker is not in a territory. On the current Broker, there is no local gateway to the specified remote territory. territory_name is full.

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.

webMethods Broker Administration Java API Programmers 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. Possible Exceptions
BrokerInvalidClientException BrokerNoPermissionException BrokerNotInTerritoryException

Meaning The BrokerAdminClient has been destroyed or disconnected. The BrokerAdminClient does not have permission to browse the Broker. The Broker is not a member of a territory.

See Also: BrokerAdminClient.setTerritoryACL getTerritoryGatewayACL

BrokerAccessControlList getTerritoryGatewayACL( String territory_name) throws BrokerException

territory_name

The name of the territory whose gateway ACL is to be returned.

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. Possible Exceptions
BrokerInvalidClientException BrokerNoPermissionException BrokerNotInTerritoryException BrokerUnknownTerritoryException

Meaning The BrokerAdminClient has been destroyed or disconnected. The BrokerAdminClient does not have permission to browse the Broker. The Broker is not a member of a territory. There is no gateway to the specified territory from this client's Broker.

See Also: BrokerAdminClient.setTerritoryGatewayKeepAlive getTerritoryGatewayKeepAlive

int getTerritoryGatewayKeepAlive( String territory_name) throws BrokerException

248

webMethods Broker Administration Java API Programmers Guide Version 8.2

12 Java API Administration Reference

territory_name

The name of the territory whose keep-alive status you want to check. Meaning The BrokerAdminClient has been destroyed or disconnected territory_name is null

Possible Exceptions
BrokerInvalidClientException BrokerNullParameterException

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

territory_name

The name of the territory to which updates are accepted or refused.

Returns whether a territory gateway refuses all updates made in a connected territory (true) or accepts all the updates (false). Possible Exceptions
BrokerInvalidClientException BrokerNoPermissionException BrokerNotInTerritoryException BrokerNullParameterException BrokerUnknownTerritoryException

Meaning The BrokerAdminClient has been destroyed or disconnected. The BrokerAdminClient does not have permission to browse the Broker. The Broker is not a member of a territory. The territory_name parameter is null. There is no gateway to the specified territory from this client's Broker.

See Also: BrokerAdminClient.setTerritoryGatewayRefuseAllUpdates

webMethods Broker Administration Java API Programmers Guide Version 8.2

249

12 Java API Administration Reference

getTerritoryGatewayRefuseEventTypeUpdates
public void getTerritoryGatewayRefuseEventTypeUpdates( String territory_name, BrokerSharedEventTypeRefuseUpdateInfo[] infos) throws BrokerException

territory_name infos

The name of the territory for which updates made in a neighboring territory are refused. Specifies whether the events and updates for a specified document type are refused.

Returns information about whether updates for a document type that are made in a connected territory are refused. Possible Exceptions
BrokerInvalidClientException BrokerNoPermissionException BrokerNotInTerritoryException BrokerNullParameterException BrokerUnknownTerritoryException

Meaning The BrokerAdminClient has been destroyed or disconnected. The BrokerAdminClient does not have permission to browse the Broker. The Broker is not a member of a territory. The territory_name parameter is null. There is no gateway to the specified territory from this client's Broker.

See Also: BrokerAdminClient.setTerritoryGatewayRefuseEventTypeUpdates getTerritoryGatewaySharedEventTypes

void getTerritoryGatewaySharedEventTypes( String territory_name, BrokerSharedEventTypeInfo infos[]) throws BrokerException

territory_name infos

The name of the territory whose event types are shared. The shared event type information.

Gets the complete list of event types shared across a territory gateway. See BrokerSharedEventTypeInfo for more information. Possible Exceptions
BrokerInvalidClientException

Meaning The BrokerAdminClient has been destroyed or disconnected

250

webMethods Broker Administration Java API Programmers Guide Version 8.2

12 Java API Administration Reference

Possible Exceptions
BrokerInvalidSubscriptionException BrokerInvalidTypeDefException BrokerNoPermissionException BrokerNotInTerritoryException BrokerNotRunningException BrokerNullParameterException

Meaning A parse error was encountered in one of the elements contained in infos. One or more of the event types is incompatible with the type definition on the remote Broker. The client does not have permission to modify the Broker. The Broker to which this client is connected is not part of a territory. The gateway connection is currently not open. 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. An event type in infos does not have accept_subscribe permission, but has a nonempty subscription_filter. An element in infos does not exist on either Broker in the gateway. If this exception is thrown, no changes are applied. There is no gateway to the specified territory from the local Broker.

BrokerOutOfRangeException

BrokerUnknownEventTypeException

BrokerUnknownTerritoryException

See Also: BrokerAdminClient.setTerritoryGatewaySharedEventTypes getTerritoryGatewayStats

BrokerEvent getTerritoryGatewayStats( String territory_name) throws BrokerException

territory_name

The name of the territory whose gateway statistics are to be returned.

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.

webMethods Broker Administration Java API Programmers Guide Version 8.2

251

12 Java API Administration Reference

Field Name
authProtocol

Type
unicode_string

Description 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". 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". The IP address of the remote Broker. Set to an empty string if the gateway is not connected. The level of encryption being used. Only set if encryptProtocol is set. Currently supported values are "USDomestic" and "USExport". The encryption protocol being used. Only set if connectedFrom is not empty. The only values currently supported is "SSL". The version of the encryption protocol being used. Only set if encryptProtocol is not empty. Currently supported values are "2" and "3". The name of the gateway Broker's host. The name of the gateway Broker. The time the Broker was last connected. Set to zero if never connected. Time when an event was last enqueued for the gateway. Time when an event was last forwarded across the gateway. Set to zero if no events have been forwarded.

authVersion

unicode_string

connectedFrom

unicode_string

encryptLevel

unicode_string

encryptProtocol

unicode_string

encryptVersion

unicode_string

gatewayHost gatewayBrokerName lastConnectTime

unicode_string unicode_string BrokerDate

lastEventEnqueueTime lastEventForwardTime

BrokerDate BrokerDate

252

webMethods Broker Administration Java API Programmers Guide Version 8.2

12 Java API Administration Reference

Field Name
lastEventReceiveTime

Type
BrokerDate

Description Time when an event was last received across the gateway. Set to zero if no events have been received. Current time on the Broker host. Number of events that were forwarded across the gateway. The number of events received across the gateway. Number of events enqueued for the gateway. The current size, in bytes, of the gateway's queue. The highest number of events in the gateway's queue. Time when queueHighestLength was last changed. The number of events currently in the gateway's queue. The name of the territory. The date of the Broker's certificate became valid. The serial number of the Broker's certificate. only set if authProtocol is set to "SSL". The date the Broker's certificate expires. The status of the other Broker's certificate. This field is only set if authProtocol is set to "SSL". The distinguished name s of the other Broker's certificate. This field is only set if authProtocol is set to "SSL". 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 numEventsForwarded numEventsReceived numEventsEnqueued queueByteSize queueHighestLength queueHighestLengthTime queueLength remoteTerritoryName sslCertBeginDate sslCertSerialNumber

BrokerDate int int int int int BrokerDate int unicode_string BrokerDate unicode_string

sslCertEndDate sslCertStatus

BrokerDate unicode_string

sslDistinguishedName

unicode_string

sslIssuerDistinguishedName

unicode_string

webMethods Broker Administration Java API Programmers Guide Version 8.2

253

12 Java API Administration Reference

Field Name
gateway_pause

Type
boolean

Description 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. The time when the gateway was paused. If outbound traffic is not currently paused for territory_name, this parameter will be 0. 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. The session id from which the gateway was paused. If outbound traffic is not currently paused for territory_name, the value will be 0.

gateway_pause_time

date

gateway_pause_client

String

gateway_pause_session

integer

Possible Exceptions
BrokerInvalidClientException BrokerNoPermissionException BrokerNotInTerritoryException BrokerNullParameterException BrokerUnknownTerritoryException

Meaning The BrokerAdminClient has been destroyed or disconnected. The BrokerAdminClient does not have permission to get the territory statistics. This client's Broker is not part of a territory. The territory_name parameter is null. There is no gateway to the specified territory from this client's Broker.

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.

254

webMethods Broker Administration Java API Programmers Guide Version 8.2

12 Java API Administration Reference

Possible Exceptions
BrokerInvalidClientException BrokerNoPermissionException BrokerNotInTerritoryException

Meaning The BrokerAdminClient has been destroyed or disconnected. The BrokerAdminClient does not have permission to get the territory statistics. This client's Broker is not part of a territory.

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: Field Name
brokers

Type
structure[]

Description The time the event type was created. This includes changes to the definition, the time-tolive setting, or any infoset. A value of zero means there have been no changes since this event type was created 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". 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". The Broker host name. The Broker Server name. Set to true if the Broker is currently connected. The Broker's description.

brokers.authProtocol

unicode_string

brokers.authVersion

unicode_string

brokers.brokerHost brokers.brokerName brokers.connectedFrom brokers.description

unicode_string unicode_string boolean unicode_string

webMethods Broker Administration Java API Programmers Guide Version 8.2

255

12 Java API Administration Reference

Field Name
brokers.encryptLevel

Type
unicode_string

Description The level of encryption being used. Only set if encryptProtocol is set. Currently supported values are "USDomestic" and "USExport". The encryption protocol being used. Only set if connectedFrom is not empty. The only values currently supported is "SSL". The version of the encryption protocol being used. Only set if encryptProtocol is not empty. Currently supported values are "2" and "3". The time the Broker was last connected. Set to zero if never connected. The time an event was last enqueued for the Broker. Set to zero if no events have ever be enqueued. Time when an event of this type was last forwarded to the Broker. Set to zero if no events have been forwarded. Time when an event was last received by the Broker. Set to zero if no events have been received. Number of events that were enqueued for the Broker. Number of events that were forwarded to the Broker. The number of events received by the Broker. The current size, in bytes, of the Broker's queue. The highest number of events in the Broker's queue.

brokers.encryptProtocol

unicode_string

brokers.encryptVersion

unicode_string

brokers.lastConnectTime

BrokerDate

brokers.lastEventEnqueueTime

BrokerDate

brokers.lastEventForwardTime

BrokerDate

brokers.lastEventReceiveTime

BrokerDate

brokers.numEventsEnqueued brokers.numEventsForwarded brokers.numEventsReceived brokers.queueByteSize brokers.queueHighestLength

int int int int int

256

webMethods Broker Administration Java API Programmers Guide Version 8.2

12 Java API Administration Reference

Field Name
brokers.queueHighestLengthTime

Type
BrokerDate

Description Time when

queueHighestLength

was last

changed.
brokers.queueLength int

The number of events currently in the Broker's queue. The date of the Broker's certificate became valid. The serial number of the Broker's certificate. only set if authProtocol is set to "SSL". The date the Broker's certificate expires. The status of the Broker's certificate. This field is only set if authProtocol is set to "SSL". The distinguished name s of the Broker's certificate. This field is only set if authProtocol is set to "SSL". The distinguished name s of the issuer of the other Broker's certificate. This field is only set if authProtocol is set to "SSL". Current time on the Broker host. The name of the territory.

brokers.sslCertBeginDate brokers.sslCertSerialNumber

BrokerDate unicode_string

brokers.sslCertEndDate brokers.sslCertStatus

BrokerDate unicode_string

brokers.sslDistinguishedName

unicode_string

brokers.sslIssuerDistinguishedName

unicode_string

now territoryName

BrokerDate unicode_string

Possible Exceptions
BrokerInvalidClientException BrokerNoPermissionException BrokerNotInTerritoryException

Meaning The BrokerAdminClient has been destroyed or disconnected. The BrokerAdminClient does not have permission to get the territory statistics. This client's Broker is not part of a territory.

webMethods Broker Administration Java API Programmers 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
now transaction transactions.transactionId transactions.externalId transactions.clientId transactions.sessionId transactions.state transactions.createdTime transactions.endedTime transactions.preparedTime transactions.closedTime transactions.closedReason transactions.unpreparedTimeout transactions.preparedTimeoutInterval transactions.preparedTimeout transactions.numEventsReceived transactions.numEventsAcknowledged transactions.numEventsPublished

Type
BrokerDate struct[] long UnicodeString UnicodeString int int BrokerDate BrokerDate BrokerDate BrokerDate int BrokerDate int BrokerDate int int int

Exception
BrokerInvalidClientException BrokerNoPermissionException

Description The BrokerAdminClient has been destroyed or disconnected. The BrokerAdminClient does not have permission to get the territory statistics.

258

webMethods Broker Administration Java API Programmers 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
now transactions[] transactions.transactionId transactions.externalId transactions.clientId transactions.sessionId transactions.state transactions.createdTime transactions.endedTime transactions.preparedTime transactions.closedTime transactions.closedReason transactions.unpreparedTimeout transactions.preparedTimeoutInterval transactions.preparedTimeout transactions.numEventsReceived transactions.numEventsAcknowledged transactions.numEventsPublished

Type
BrokerDate struct[] long UnicodeString UnicodeString int int BrokerDate BrokerDate BrokerDate BrokerDate int BrokerDate int BrokerDate int int int

Exception
BrokerInvalidClientException BrokerInvalidClientIdException BrokerNullParameterException BrokerNoPermissionException

Description The client has been destroyed or disconnected. client_id contains illegal characters. client_id is null. Client does not have sufficient permissions.

webMethods Broker Administration Java API Programmers 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

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

broker_name

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. Possible Exceptions
BrokerHostNotFoundException BrokerInTerritoryException BrokerInvalidClientException BrokerNoPermissionException

Meaning The specified broker_host does not exist. This client's Broker is already a member of a territory. The BrokerAdminClient has been destroyed or disconnected. The BrokerAdminClient does not have permission to modify the Broker's properties or the Broker is not licensed for Broker interconnection. The Broker specified by broker_name is not a member of a territory. The parameter broker_host or broker_name is null. There is another Broker in the specified territory with the same name If the territory requires SSL and the joining Broker does not support SSL.

BrokerNotInTerritoryException BrokerNullParameterException BrokerOutOfRangeException BrokerSecurityException

260

webMethods Broker Administration Java API Programmers Guide Version 8.2

12 Java API Administration Reference

Possible Exceptions
BrokerUnknownBrokerNameException

Meaning The specified broker_name does not exist on the specified broker_host.

See Also: BrokerAdminClient.createTerritory, BrokerAdminClient.getBrokersInTerritory, BrokerAdminClient.getTerritoryStats, BrokerAdminClient.leaveTerritory, and BrokerAdminClient.removeBrokerFromTerritory

leave Methods
leaveCluster
void leaveCluster( int msecs, boolean forced) throws BrokerException

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. If set to true, the Broker will leave the cluster even if it cannot contact other cluster members within the specified time out interval.

forced

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. Possible Exceptions
BrokerInvalidClientException BrokerNoPermissionException BrokerNotInClusterException

Meaning The BrokerAdminClient has been destroyed or disconnected. The BrokerAdminClient does not have permission to modify the Broker's properties. The Broker is not a member of a cluster.

webMethods Broker Administration Java API Programmers 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

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. If set to true, the Broker will leave the territory even if it cannot contact other territory members within the specified time out interval.

forced

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. Possible Exceptions
BrokerInvalidClientException BrokerNoPermissionException BrokerNotInTerritoryException

Meaning The BrokerAdminClient has been destroyed or disconnected. The BrokerAdminClient does not have permission to modify the Broker's properties. The Broker is not a member of a territory.

See Also: BrokerAdminClient.createTerritory, BrokerAdminClient.getBrokersInTerritory, BrokerAdminClient.getTerritoryStats, BrokerAdminClient.joinTerritory, and BrokerAdminClient.removeBrokerFromTerritory

262

webMethods Broker Administration Java API Programmers 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

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 client_id

The name of the Broker Server. If set to null, the default Broker name is used. The client identifier, identifying the client as the one that was previously disconnected. See the webMethods Broker Client Java API Programmers Guide for more information on client identifiers. The name of the client group for the new Broker client. Client groups are discussed in Administering webMethods Broker. The name of the application that will contain the new Broker client. 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.

client_group app_name desc

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

webMethods Broker Administration Java API Programmers Guide Version 8.2

263

12 Java API Administration Reference

Possible Exceptions
BrokerClientContentionException

Meaning Another Broker client is already using the specified client_id. For clients with shared state, the maximum number of reconnects has been exceeded. A problem occurred establishing the connection. The specified broker_host does not exist. The client_id contains invalid characters. Permission to join the client_group as an administrative client was denied. A Broker could not be found on the broker_host. The broker_host, client_id, client_group, or app_name parameter is null. The specified broker_name does not exist. If broker_name was null, then there is no default Broker. The specified client_group_name does not exist on the Broker. The specified client_id does not exist on the Broker.

BrokerCommFailureException BrokerHostNotFoundException BrokerInvalidClientIdException BrokerNoPermissionException BrokerNotRunningException BrokerNullParameterException BrokerUnknownBrokerNameException

BrokerUnknownClientGroupException BrokerUnknownClientIdException

See Also: BrokerAdminClient.BrokerAdminClient, BrokerAdminClient.reconnectAdmin, as well as BrokerClient.destroy and BrokerClient.disconnect (described in the webMethods Broker Client Java API Programmers Guide)

reconnect Method
reconnectAdmin
static BrokerAdminClient reconnectAdmin( String broker_host, String broker_name, String client_id, BrokerConnectionDescriptor desc) throws BrokerException

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 Programmers Guide Version 8.2

12 Java API Administration Reference

broker_name client_id

The name of the Broker Server. If set to null, the default Broker name is used. The client identifier, identifying the client as the one that was previously disconnected. See the webMethods Broker Client Java API Programmers Guide for more information on client identifiers. 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.

desc

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 Programmers 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. Possible Exceptions
BrokerClientContentionException

Meaning Another Broker client is already using the specified client_id. For clients with shared state, the maximum number of reconnects has been exceeded. A problem occurred establishing the connection. The specified broker_host does not exist. The client_id contains invalid characters. Permission to join the client_group as an administrative client was denied. A Broker could not be found on the broker_host. The broker_host or client_id parameter is null.

BrokerCommFailureException BrokerHostNotFoundException BrokerInvalidClientIdException BrokerNoPermissionException BrokerNotRunningException BrokerNullParameterException

webMethods Broker Administration Java API Programmers Guide Version 8.2

265

12 Java API Administration Reference

Possible Exceptions
BrokerUnknownBrokerNameException

Meaning The specified broker_name does not exist. If broker_name was null, then there is no default Broker. The specified client_id does not exist on the Broker.

BrokerUnknownClientIdException

See Also: BrokerAdminClient.BrokerAdminClient and BrokerAdminClient.newOrReconnectAdmin, as well as BrokerClient.destroy and BrokerClient.disconnect (described in the webMethods Broker Client Java API Programmers 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. Possible Exceptions
BrokerBadStateException BrokerIncompatibleVersionException BrokerInvalidClientException

Meaning The client's Broker is currently not locked or the lock is being held by another client. The Broker Server does not support this operation. The BrokerAdminClient has been destroyed or disconnected.

See Also: BrokerAdminClient.acquireChangeLock

remove Methods
removeBrokerFromCluster
void removeBrokerFromCluster( String broker_host, String broker_name) throws BrokerException

266

webMethods Broker Administration Java API Programmers Guide Version 8.2

12 Java API Administration Reference

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. The name of the Broker Server to be removed from the cluster to which this client's Broker belongs.

broker_name

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. Possible Exceptions
BrokerHostNotFoundException BrokerInvalidClientException BrokerNoPermissionException BrokerNotInClusterException BrokerNullParameterException BrokerOutOfRangeException BrokerUnknownBrokerNameException

Meaning The specified host cannot be located. The BrokerAdminClient has been destroyed or disconnected. The BrokerAdminClient does not have permission to modify the Broker's properties. The Broker to which this BrokerAdminClient is connected is not in any cluster. The parameter broker_host or broker_name is null. An attempt was made to remove the current Broker. The specified broker_name on the specified broker_host is not a member of the cluster.

See Also: BrokerAdminClient.createCluster, BrokerAdminClient.getBrokersInCluster, BrokerAdminClient.getClusterStats, BrokerAdminClient.addBrokerToCluster, and BrokerAdminClient.leaveCluster. removeBrokerFromTerritory

void removeBrokerFromTerritory( String broker_host, String broker_name) throws BrokerException

webMethods Broker Administration Java API Programmers Guide Version 8.2

267

12 Java API Administration Reference

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. The name of the Broker Server to be removed from the territory to which this client's Broker belongs.

broker_name

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. Possible Exceptions
BrokerHostNotFoundException BrokerInvalidClientException BrokerNoPermissionException BrokerNotInTerritoryException BrokerNullParameterException BrokerOutOfRangeException BrokerUnknownBrokerNameException

Meaning The specified host cannot be located. The BrokerAdminClient has been destroyed or disconnected. The BrokerAdminClient does not have permission to modify the Broker's properties. The Broker to which this BrokerAdminClient is connected is not in any territory. The parameter broker_host or broker_name is null. An attempt was made to remove the current Broker. The specified broker_name on the specified broker_host is not a member of the territory.

See Also: BrokerAdminClient.createTerritory, BrokerAdminClient.getBrokersInTerritory, BrokerAdminClient.getTerritoryStats, BrokerAdminClient.joinTerritory, and BrokerAdminClient.leaveTerritory

set Methods
setBrokerDescription
void setBrokerDescription( String description) throws BrokerException

description

A string containing the new description to be set for the Broker.

268

webMethods Broker Administration Java API Programmers 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. Possible Exceptions
BrokerInvalidClientException BrokerNoPermissionException BrokerNullParameterException

Meaning The BrokerAdminClient has been destroyed or disconnected. The BrokerAdminClient does not have permission to set the Broker's description. The description parameter is null.

See Also: BrokerAdminClient.getBrokerDescription setClientGroupAccessLabelRequired

void setClientGroupAccessLabelRequired( String client_group_name, boolean required) throws BrokerException

client_group_name required

A string containing the name of the client group whose access control list is to be set. If set to true, an access label will be required.

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. Possible Exceptions
BrokerInvalidClientException BrokerNoPermissionException BrokerNullParameterException BrokerUnknownClientGroupException

Meaning The BrokerAdminClient has been destroyed or disconnected. The BrokerAdminClient does not have permission to modify the client group. The client_group_name parameter is null. The specified client_group_name does not exist on the Broker.

See Also: BrokerAdminClient.getClientGroupInfo

webMethods Broker Administration Java API Programmers Guide Version 8.2

269

12 Java API Administration Reference

setClientGroupACL
void setClientGroupACL( String client_group_name, BrokerAcessControlList acl) throws BrokerException

client_group_name acl

A string containing the name of the client group whose access control list is to be set. The access control list to set.

Sets the list of names that are allowed to create Broker clients which belong to the specified client group. See AccessControlList for more information. Possible Exceptions
BrokerInvalidAccessListException BrokerInvalidClientException BrokerNoPermissionException BrokerNullParameterException BrokerUnknownClientGroupException

Meaning The access control list is invalid. The BrokerAdminClient has been destroyed or disconnected. The BrokerAdminClient does not have permission to set the client group's Access Control List. The client_group_name or acl parameter is null. The specified client_group_name does not exist on the Broker.

See Also: BrokerAdminClient.getClientGroupACL setClientGroupCanPublishList

void setClientGroupCanPublishList( String client_group_name, String event_type_names[]) throws BrokerException

client_group_name event_type_names

A string containing the name of the client group whose canpublish list is to be set. An array of strings containing the event type names to be set as the can-publish list.

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.

270

webMethods Broker Administration Java API Programmers Guide Version 8.2

12 Java API Administration Reference

Possible Exceptions
BrokerInvalidClientException BrokerNoPermissionException BrokerNullParameterException

Meaning The BrokerAdminClient has been destroyed or disconnected. The BrokerAdminClient does not have permission to set the client group's can-publish list. The client_group_name or event_type_names parameter was null or an entry in the event_type_names array is null. The specified client_group_name does not exist on the Broker. 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.

BrokerUnknownClientGroupException BrokerUnknownEventTypeException

See Also: BrokerAdminClient.getClientGroupCanPublishList, BrokerAdminClient.getClientGroupCanSubscribeList, and BrokerAdminClient.setClientGroupCanSubscribeList setClientGroupCanSubscribeList

void setClientGroupCanSubscribeList( String client_group_name, String event_type_names[]) throws BrokerException

client_group_name event_type_names

A string containing the name of the client group whose cansubscribe list is to be set. An array of strings containing the event type names to be set as the can-subscribe list.

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
BrokerInvalidClientException BrokerNoPermissionException BrokerNullParameterException

Meaning The BrokerAdminClient has been destroyed or disconnected. The BrokerAdminClient does not have permission to set the client group's can-publish list. The client_group_name parameter was null or an entry in the event_type_names array is null.

webMethods Broker Administration Java API Programmers Guide Version 8.2

271

12 Java API Administration Reference

Possible Exceptions
BrokerUnknownClientGroupException BrokerUnknownEventTypeException

Meaning The specified client_group_name does not exist on the Broker. 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.

See Also: BrokerAdminClient.getClientGroupCanSubscribeList, BrokerAdminClient.getClientGroupCanPublishList, and BrokerAdminClient.setClientGroupCanPublishList setClientGroupDescription

void setClientGroupDescription( String client_group_name, String description) throws BrokerException

client_group_name description

A string containing the name of the client group whose description is to be set. A string containing the description to be set for the client group.

Sets the description of the specified client group. You can use the BrokerAdminClient.getClientGroupInfo method to retrieve the description. Possible Exceptions
BrokerInvalidClientException BrokerNoPermissionException BrokerNullParameterException BrokerUnknownClientGroupException

Meaning The BrokerAdminClient has been destroyed or disconnected. The BrokerAdminClient does not have permission to set the client group's description. The client_group_name or description parameter is null. The specified client_group_name does not exist on the Broker.

See Also: BrokerAdminClient.getClientGroupInfo and BrokerAdminClient.getClientGroupNames

272

webMethods Broker Administration Java API Programmers 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

client_group_name event_type_names

The name of the client group whose event types are to be logged. List of the event type names to be logged.

Set the list of event types that are logged when acknowledged by a client in the specified client group. Possible Exceptions
BrokerInvalidClientException BrokerNoPermissionException BrokerNullParameterException BrokerUnknownEventTypeException

Meaning The client has been destroyed or disconnected. The client does not have permission to modify the client group. If client_group_name or event_type_names is null, or if any entry in the array is null. If an event type is listed that does not exist in the Broker. In this case, the can publish list is not altered.

setClientGroupLogPublishList
void setClientGroupLogPublishList( java.lang.String client_group_name, java.lang.String[] event_type_names) throws BrokerException

client_group_name event_type_names

The name of the client group whose event types are to be logged. List of the event type names to be logged.

Set the list of event types that are logged when published or delivered by a client in the the specified client group. Possible Exceptions
BrokerInvalidClientException BrokerNoPermissionException BrokerNullParameterException

Meaning The client has been destroyed or disconnected. The client does not have permission to modify the client group. If client_group_name or event_type_names is null, or if any entry in the array is null.

webMethods Broker Administration Java API Programmers Guide Version 8.2

273

12 Java API Administration Reference

Possible Exceptions
BrokerUnknownEventTypeException

Meaning If an event type is listed that does not exist in the Broker. In this case, the can publish list is not altered.

setClientGroupRequiredEncryption
void setClientGroupRequiredEncryption( String client_group_name, int level) throws BrokerException

client_group_name level

The name of the client group whose required encryption level is being set. The level of encryption required by the client group. Must be a BrokerConnectionDescriptorENCRYPT_LEVEL_* values described in the webMethods Broker Client Java API Programmers Guide.

Set the required encryption for the specified client group. This client group's current value can be acquired using the BrokerAdminClient.getClientGroupInfo method. Possible Exceptions
BrokerInvalidClientException BrokerNoPermissionException

Meaning The BrokerAdminClient has been destroyed or disconnected. The BrokerAdminClient does not have permission to modify the properties of the specified client group. The client _group parameter is null. The parameter level contains an invalid value. The specified client group does not exist on the Broker.

BrokerNullParameterException BrokerOutOfRangeException BrokerUnknownClientGroupException

See Also: BrokerAdminClient.getClientGroupInfo setClientInfosetById

void setClientInfosetById( String client_id, BrokerEvent infoset) throws BrokerException

client_id

The identifier of the Broker client whose infoset is to be returned.

274

webMethods Broker Administration Java API Programmers Guide Version 8.2

12 Java API Administration Reference

infoset

The infoset to be set for the Broker client.

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 Programmers Guide. Possible Exceptions
BrokerInvalidClientException BrokerNoPermissionException

Meaning The BrokerAdminClient has been destroyed or disconnected. The BrokerAdminClient does not have permission to modify the properties of the specified Broker client. The client_id or infoset parameter is null. The specified client does not exist on the Broker.

BrokerNullParameterException BrokerUnknownClientIdException

See Also: BrokerAdminClient.getClientInfosetById setClientLastPublishSequenceNumberById

void setClientLastPublishSequenceNumberById( String client_id, long seqn) throws BrokerException

client_id seqn

A string containing the client identifier whose last-published sequence number is to be set. The new last-published sequence number to set.

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. Possible Exceptions
BrokerInvalidClientException

Meaning The BrokerAdminClient has been destroyed or disconnected.

webMethods Broker Administration Java API Programmers Guide Version 8.2

275

12 Java API Administration Reference

Possible Exceptions
BrokerNoPermissionException

Meaning The BrokerAdminClient does not have permission to modify the properties of the specified Broker client. The client_id parameter is null. The seqn parameter is less than zero. The specified client does not exist on the Broker.

BrokerNullParameterException BrokerOutOfRangeException BrokerUnknownClientIdException

See Also: BrokerAdminClient.getClientInfoById setClientStateShareLimitById

void setClientStateShareLimitById( String client_id, int limit) throws BrokerException

client_id limit

A string containing the client identifier whose state share limit is to be set. 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.

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 Programmers Guide. You can obtain a list of client identifiers by invoking the one of the following methods: getClientIds getClientIdsByClientGroup getClientIdsWhichAreSubscribed Possible Exceptions
BrokerInvalidClientException BrokerNoPermissionException

Meaning The BrokerAdminClient has been destroyed or disconnected. The BrokerAdminClient does not have permission to modify the client's queue or the client is not currently sharing its state.

276

webMethods Broker Administration Java API Programmers Guide Version 8.2

12 Java API Administration Reference

Possible Exceptions
BrokerNullParameterException BrokerOutOfRangeException BrokerUnknownClientIdException

Meaning The client_id parameter is null. The limit parameter is zero or less than -1. The specified client_id does not exist on the Broker.

See Also: BrokerAdminClient.getClientInfoById setClusterACL

void setClusterACL( BrokerAccessControlList acl) throws BrokerException

acl

The access control list to set for this Broker's cluster.

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 interBroker 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. Possible Exceptions
BrokerInvalidAccessListException BrokerInvalidClientException BrokerNoPermissionException BrokerNotInClusterException BrokerNullParameterException

Meaning The acl variable does not contain a valid access control list. The BrokerAdminClient has been destroyed or disconnected. The BrokerAdminClient does not have permission to modify the Broker. The Broker to which this client is connected is not part of a cluster. The acl parameter is null.

See Also: BrokerAdminClient.getClusterACL

webMethods Broker Administration Java API Programmers Guide Version 8.2

277

12 Java API Administration Reference

setClusterGatewayACL
void setClusterGatewayACL( String cluster_name, String broker_name, BrokerAccessControlList acl) throws BrokerException

cluster_name broker_name acl

The name of the cluster whose gateway ACL is to be set. The name of the Broker in the specified remote cluster to which the ACL is to be set. The access control list.

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. Possible Exceptions
BrokerInvalidAccessListException BrokerInvalidClientException BrokerNoPermissionException BrokerNotInClusterException BrokerNullParameterException BrokerOutOfRangeException BrokerUnknownClusterException

Meaning The acl variable does not contain a valid access control list. The BrokerAdminClient has been destroyed or disconnected. The BrokerAdminClient does not have permission to modify the Broker. The Broker to which this client is connected is not part of a cluster. The cluster_name, broker_name or acl parameter is null. The acl contains more than one user entry or more than one authenticator entry. There is no gateway to the specified cluster from this Broker.

See Also: BrokerAdminClient.getClusterGatewayACL

278

webMethods Broker Administration Java API Programmers Guide Version 8.2

12 Java API Administration Reference

setClusterGatewayKeepAlive
void setClusterGatewayKeepAlive( String cluster_name, String broker_name, int KeepAlive) throws BrokerException

cluster_name broker_name KeepAlive

The name of the cluster to which you want the gateway Broker to issue keep-alive messages. The name of the gateway Broker in the specified remote cluster you want to enable or disable keep-alive messages. 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. Meaning The BrokerAdminClient has been destroyed or disconnected The cluster_name or broker_name parameter is null. The value of KeepAlive is less than Zero (0). The BrokerAdminClient does not have permission to modify the Broker. The Broker to which this client is connected is not part of a cluster. There is no gateway to the specified cluster from this Broker. Gateway Broker does not support the keepalive feature.

Possible Exceptions
BrokerInvalidClientException BrokerNullParameterException BrokerOutOfRageException BrokerNoPermissionException BrokerNotInClusterException BrokerUnknownClusterException BrokerIncompatibleVersionException

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

webMethods Broker Administration Java API Programmers 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

cluster_name broker_name pause

The name of the cluster whose events you want the gateway Broker to hold. The name of the gateway Broker in the specified cluster to which you want to prevent from forwarding events. 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.

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. Possible Exceptions
BrokerInvalidClientException BrokerNullParameterException BrokerBadStateException BrokerNoPermissionException BrokerNotInClusterException BrokerUnknownClusterException BrokerIncompatibleVersionException BrokerQueueBrowserException

Meaning The BrokerAdminClient has been destroyed or disconnected. The cluster_name or broker_name is null. The cluster gateway is already paused or resumed. The BrokerAdminClient does not have permission to modify the Broker. The Broker to which this client is connected is not a member of a cluster. There is no gateway to the specified cluster from this Broker. The gateway Broker does not support this feature. The gateway forwarding queue is locked by a queue browser.

280

webMethods Broker Administration Java API Programmers Guide Version 8.2

12 Java API Administration Reference

setClusterGatewayRefuseAllUpdates
void setClusterGatewayRefuseAllUpdates( String cluster_name, String broker_name, boolean refuse_updates) throws BrokerException

cluster_name broker_name

The name of the cluster to which updates are refused. The name of the Broker in the specified cluster. This Broker is used to identify the right gateway link for setting this permission. Specify whether the cluster will refuse all updates from a neighboring cluster connected by a gateway (true).

refuse_updates

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. Possible Exceptions
BrokerInvalidClientException BrokerNoPermissionException BrokerNotInClusterException BrokerNullParameterException BrokerUnknownClusterException

Meaning The BrokerAdminClient has been destroyed or disconnected. The BrokerAdminClient does not have permission to browse the Broker. The Broker is not a member of a cluster. The cluster_name or broker_name parameter is null. There is no gateway to the specified cluster from this client's Broker.

See Also: BrokerAdminClient.getClusterGatewayRefuseAllUpdates setClusterGatewaySecurity

void setClusterGatewaySecurity( String cluster_name, String broker_name, int auth_type, int encrypt_level) throws BrokerException

cluster_name broker_name

The name of the cluster whose gateway security is to be set. The name of the Broker in the specified remote cluster to which this Broker is connected.

webMethods Broker Administration Java API Programmers Guide Version 8.2

281

12 Java API Administration Reference

auth_type encrypt_level

The type of authentication to set for the gateway, specified as one of the AUTH_TYPE_* values defined by BrokerAdminClient. 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 Programmers Guide.

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. Possible Exceptions
BrokerInvalidClientException BrokerNoPermissionException BrokerNotInClusterException BrokerNullParameterException BrokerOutOfRangeException BrokerUnknownClusterException

Meaning The BrokerAdminClient has been destroyed or disconnected. The BrokerAdminClient does not have permission to modify the Broker. The Broker to which this client is connected is not a member of a cluster. The cluster_name or broker_name parameter is null. The auth_type or encrypt_level parameter contains an invalid value. There is no gateway to the specified cluster from this Broker.

See also BrokerAdminClient.getAllClusterGateways and BrokerAdminClient.getLocalClusterGateways setClusterGatewaySharedEventTypes

void setClusterGatewaySharedEventTypes( String cluster_name, String broker_name, BrokerSharedEventTypeInfo[] infos) throws BrokerException

282

webMethods Broker Administration Java API Programmers Guide Version 8.2

12 Java API Administration Reference

cluster_name broker_name infos

The name of the cluster whose shared event types are to be set. The name of the Broker in specified remote cluster. The shared event type information.

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 Programmers Guide for complete information on event filtering See BrokerSharedEventTypeInfo for more information. Possible Exceptions
BrokerInvalidClientException BrokerInvalidSubscriptionException BrokerInvalidTypeDefException BrokerNoPermissionException BrokerNotInClusterException BrokerNotRunningException BrokerNullParameterException

Meaning The BrokerAdminClient has been destroyed or disconnected A parse error was encountered in one of the elements contained in infos. One or more of the event types is incompatible with the type definition on the remote Broker. The client does not have permission to modify the Broker. The Broker to which this client is connected is not part of a cluster. The gateway connection is currently not open. 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. An event type in infos does not have accept_subscribe permission, but has a nonempty subscription_filter. An element in infos does not exist on either Broker in the gateway. If this exception is thrown, no changes are applied.

BrokerOutOfRangeException

BrokerUnknownEventTypeException

webMethods Broker Administration Java API Programmers Guide Version 8.2

283

12 Java API Administration Reference

Possible Exceptions
BrokerUnknownClusterException

Meaning There is no gateway to the specified cluster from the local Broker.

See Also: BrokerAdminClient.getClusterGatewaySharedEventTypes setClusterPrimaryGateway

public void setClusterPrimaryGateway( String cluster_name, String broker_name) throws BrokerException

cluster_name broker_name

The name of the cluster to which the primary gateway connection has to be set. The name of the Broker in the specified cluster that will be used for the primary gateway connection.

Set the primary gateway connection from this Broker to the remote cluster specified by cluster_name and broker_name. Possible Exceptions
BrokerInvalidClientException BrokerNoPermissionException BrokerNotInClusterException BrokerNullParameterException BrokerUnknownClusterException BrokerIncompatibleVersionException

Meaning The BrokerAdminClient has been destroyed or disconnected The client does not have permission to modify the Broker. The Broker to which this client is connected is not part of a cluster. The cluster_name or broker_name parameter is null. There is no gateway to the specified cluster from the local Broker. The Broker does not support cluster gateways. Broker Server version 8.2 and above support cluster gateways.

setClusterSecurity
void setClusterSecurity( int auth_type, int encrypt_level) throws BrokerException

284

webMethods Broker Administration Java API Programmers Guide Version 8.2

12 Java API Administration Reference

auth_type encrypt_level

The type of authentication to set for the cluster, specified as one of the AUTH_TYPE_* values defined by BrokerAdminClient. 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 Programmers Guide.

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. Possible Exceptions
BrokerInvalidClientException BrokerNoPermissionException BrokerNotInClusterException BrokerOutOfRangeException

Meaning The BrokerAdminClient has been destroyed or disconnected. The BrokerAdminClient does not have permission to modify the Broker. The Broker to which this client is connected is not part of a cluster. The auth_type or encrypt_level parameter contains an invalid value.

See also BrokerAdminClient.getClusterInfo setClusterStaticGatewayForwarding

void setClusterStaticGatewayForwarding( String cluster_name, String broker_name, boolean enable) throws BrokerException

cluster_name broker_name enable

The name of the cluster to which you want to enable or disable static gateway forwarding. The name of the Broker used to identify the correct gateway link for enabling or disabling static gateway forwarding. Specify whether the cluster will have static gateway forwarding to the other cluster connected by a gateway. The default is true.

Set whether to enable or disable a cluster gateway forwarding of shared documents across the gateway.

webMethods Broker Administration Java API Programmers Guide Version 8.2

285

12 Java API Administration Reference

Possible Exceptions
BrokerInvalidClientException BrokerNotInClusterException BrokerNullParameterException BrokerUnknownClusterException

Meaning The BrokerAdminClient has been destroyed or disconnected The Broker to which this client is connected is not a member of a cluster. The cluster_name or broker_name parameter is null. There is no gateway to the specified cluster from the local Broker.

setEventAdminTypeDef
void setEventAdminTypeDef( BrokerAdminTypeDef type_def) throws BrokerException

type_def

A BrokerAdminTypeDef object containing the event type definition to be set.

Sets the event type definition for the specified event type. If the event type does not exist on the Broker, it will be created. Possible Exceptions
BrokerInvalidClientException BrokerNoPermissionException

Meaning The BrokerAdminClient has been destroyed or disconnected. 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. The type_def parameter is null.

BrokerNullParameterException

See Also: BrokerAdminClient.destroyEventType, BrokerAdminClient.destroyEventTypes, BrokerAdminClient.getEventAdminTypeDef, BrokerAdminClient.getEventAdminTypeDefs, BrokerAdminClient.getEventAdminTypeDefsByScope, and BrokerAdminClient.setEventAdminTypeDefs setEventAdminTypeDefs
void setEventAdminTypeDefs( BrokerAdminTypeDef type_defs[]) throws BrokerException

type_defs

An array of BrokerAdminTypeDef objects, each element containing an event type definition to be set.

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.

286

webMethods Broker Administration Java API Programmers 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. Possible Exceptions
BrokerInvalidClientException BrokerNoPermissionException

Meaning The BrokerAdminClient has been destroyed or disconnected. 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. The type_defs parameter is null or any array entry is null.

BrokerNullParameterException

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

event_type_name infoset_name infoset

The event type with which the infoset is associated. The name of the infoset to set. If null, the type name of the event will be used as the infoset name. A BrokerEvent object which represents the infoset.

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

webMethods Broker Administration Java API Programmers Guide Version 8.2

287

12 Java API Administration Reference

Possible Exceptions
BrokerInvalidClientException BrokerInvalidEventTypeNameException BrokerNoPermissionException

Meaning The BrokerAdminClient has been destroyed or disconnected. The infoset_name is invalid. The BrokerAdminClient does not have permission to modify the event type's infoset. The event_type_name parameter is null. The event_type_name does not exist on the Broker.

BrokerNullParameterException BrokerUnknownEventTypeException

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 Programmers Guide) setEventTypeInfosets
void setEventTypeInfosets( String event_type_name, BrokerEvent infosets[]) throws BrokerException

event_type_name infosets

The event type with which the infoset is associated. An array of BrokerEvent objects which represent the infosets for the event type.

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
BrokerInvalidClientException BrokerNoPermissionException BrokerNullParameterException

Meaning The BrokerAdminClient has been destroyed or disconnected. The BrokerAdminClient does not have permission to modify the event type's infosets. The event_type_name or infosets parameter is null, or an entry in the infosets array is null.

288

webMethods Broker Administration Java API Programmers Guide Version 8.2

12 Java API Administration Reference

Possible Exceptions
BrokerUnknownEventTypeException

Meaning The event_type_name does not exist on the Broker.

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

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

client_group_names_to_destroy

event_types

client_groups

forced

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

webMethods Broker Administration Java API Programmers 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. Possible Exceptions
BrokerInvalidAccessListException BrokerInvalidClientException BrokerInvalidClientGroupException BrokerInvalidEventTypeNameException BrokerNullParameterException

Meaning An ACL, specified in one of the client_groups elements, is invalid. The BrokerAdminClient has been destroyed or disconnected. A client group name, specified in one of the client_groups elements, is invalid. An event type name, specified in one of the event_types elements, is invalid. 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. An element in client_groups specifies an invalid life_cycle or storage_type value. An element in client_groups specified an unknown event type name in a client group's can-publish or can-subscribe list.

BrokerOutOfRangeException BrokerUnknownEventTypeException

See Also: BrokerAdminClient.getEventAdminTypeDef, BrokerAdminClient.getEventAdminTypeDefs, BrokerAdminClient.getClientGroupInfo, BrokerAdminClient.getClientGroupInfos

290

webMethods Broker Administration Java API Programmers Guide Version 8.2

12 Java API Administration Reference

setPostPrepareTimeout
void setPostPrepareTimeout( int timeout_secs) throws BrokerException

timeout_secs

The post-prepare timeout in seconds.

Specifies the default value, in seconds, of the post-prepare time-out period. The postprepare time-out period is the period of time between the point when a transaction is prepared and when it is committed. Possible Exceptions
BrokerInvalidClientException BrokerNoPermissionException BrokerOutOfRangeException BrokerIncompatibleVersionException

Meaning The BrokerAdminClient has been destroyed or disconnected. The BrokerAdminClient does not have permission to modify the Broker. The timeout_secs value is out of range. The Broker does not support transaction administration.

See Also: BrokerAdminClient.getPostPrepareTimeout and BrokerAdminClient.setPostPrepareTimeoutAction setPostPrepareTimeoutAction

void setPostPrepareTimeoutAction( int action) throws BrokerException

action

BrokerAdminClient.TRANSACTION_ROLLBACK BrokerAdminClient.TRANSACTION_COMMIT.

or

Specifies whether the Broker transaction manager is to rollback or commit prepared transactions when they exceed the allotted post-prepare time-out period. The postprepare time-out period is the period of time between the point when a transaction is prepared and when it is committed. Possible Exceptions
BrokerInvalidClientException BrokerNoPermissionException BrokerOutOfRangeException

Meaning The BrokerAdminClient has been destroyed or disconnected. The BrokerAdminClient does not have permission to modify the Broker. The value of action is invalid.

webMethods Broker Administration Java API Programmers Guide Version 8.2

291

12 Java API Administration Reference

Possible Exceptions
BrokerIncompatibleVersionException

Meaning The Broker does not support transaction administration.

See Also: BrokerAdminClient.getPostPrepareTimeoutAction and BrokerAdminClient.setPostPrepareTimeout setPrePrepareTimeout

void setPrePrepareTimeout( int timeout_secs) throws BrokerException

timeout_secs

The pre-prepare timeout in seconds.

Specifies the default value, in seconds, of the pre-prepare time-out period. The preprepare time-out period is the period of time between the point when a transaction begins until it is asked to prepare. Possible Exceptions
BrokerInvalidClientException BrokerNoPermissionException BrokerOutOfRangeException BrokerIncompatibleVersionException

Meaning The BrokerAdminClient has been destroyed or disconnected. The BrokerAdminClient does not have permission to modify the Broker. The timeout_secs value is out of range. The Broker does not support transaction administration.

See Also: BrokerAdminClient.getPrePrepareTimeout setRecoverMode

void setRecoverMode(int mode) throws BrokerException

mode

RECOVER_RESTRICTED

or RECOVER_GLOBAL.

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

292

webMethods Broker Administration Java API Programmers Guide Version 8.2

12 Java API Administration Reference

Possible Exceptions
BrokerInvalidClientException BrokerNoPermissionException BrokerOutOfRangeException

Meaning The BrokerAdminClient has been destroyed or disconnected. The BrokerAdminClient does not have permission to modify the Broker. The timeout_secs value is out of range.

See Also: BrokerAdminClient.getRecoverMode setRemoteBrokerKeepAlive

int setRemoteBrokerKeepAlive( String broker_name, int KeepAlive) throws BrokerException

broker_name KeepAlive

The name of the Broker to which you want the remote Broker to issue keep-alive messages. 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. Meaning The BrokerAdminClient has been destroyed or disconnected broker_name is null KeepAlive value is < 0. A Broker does not support the keep-alive feature.

Possible Exceptions
BrokerInvalidClientException BrokerNullParameterException BrokerOutOfRageException BrokerIncompatibleVersionException

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

webMethods Broker Administration Java API Programmers 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

territory_name enable

name of the remote territory state of static gateway forwarding

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. Possible Exceptions
BrokerIncompatibleVersionException

Meaning The gateway Broker on which the static forwarding option is applied to is an earlier version than webMethods Broker version 6.5. The gateway Broker is not in the territory. territory_name is full. On the current Broker, there is no local gateway to the specified remote territory.

BrokerNotInTerritoryException BrokerNullParameterException BrokerUnknownTerritoryException

See Also: BrokerAdminClient.getStaticGatewayForwarding setTerritoryACL

void setTerritoryACL( BrokerAccessControlList acl) throws BrokerException

acl

The access control list to set for this Broker's territory.

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 interBroker connections to fail. For more information on territories, see Managing Broker Territories on page 93.

294

webMethods Broker Administration Java API Programmers 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. Possible Exceptions
BrokerInvalidAccessListException BrokerInvalidClientException BrokerNoPermissionException BrokerNotInTerritoryException BrokerNullParameterException

Meaning The acl variable does not contain a valid access control list. The BrokerAdminClient has been destroyed or disconnected. The BrokerAdminClient does not have permission to modify the Broker. The Broker to which this client is connected is not part of a territory. The acl parameter is null.

See Also: BrokerAdminClient.getTerritoryACL setTerritoryGatewayACL

void setTerritoryGatewayACL( String territory_name, BrokerAccessControlList acl) throws BrokerException

territory_name acl

The name of the territory whose gateway ACL is to be set. The access control list to set for this Broker's territory.

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

Meaning The acl variable does not contain a valid access control list. The BrokerAdminClient has been destroyed or disconnected.

webMethods Broker Administration Java API Programmers Guide Version 8.2

295

12 Java API Administration Reference

Possible Exceptions
BrokerNoPermissionException BrokerNotInTerritoryException BrokerNullParameterException BrokerOutOfRangeException BrokerUnknownTerritoryException

Meaning The BrokerAdminClient does not have permission to modify the Broker. The Broker to which this client is connected is not part of a territory. The acl parameter is null. The acl contains more than one user entry or more than one authenticator entry. There is no gateway to the specified territory from this Broker.

See Also: BrokerAdminClient.getTerritoryGatewayACL setTerritoryGatewayKeepAlive

void setTerritoryGatewayKeepAlive( String territory_name, int KeepAlive) throws BrokerException

territory_name KeepAlive

The name of the territory to which you want the gateway Broker to issue keep-alive messages. 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. Meaning The BrokerAdminClient has been destroyed or disconnected territory_name is null KeepAlive value is < 0. Gateway Broker does not support the keepalive feature.

Possible Exceptions
BrokerInvalidClientException BrokerNullParameterException BrokerOutOfRageException BrokerIncompatibleVersionException

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 keepalive feature to generate enough traffic to keep the connection alive.

296

webMethods Broker Administration Java API Programmers 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

territory_name pause

The name of the territory whose events you want the gateway Broker to hold. 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.

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. Possible Exceptions
BrokerInvalidClientException BrokerNullParameterException BrokerBadStateException BrokerNoPermissionException BrokerNotInTerritoryException BrokerUnknownTerritoryException BrokerIncompatibleVersionException

Meaning The BrokerAdminClient has been destroyed or disconnected. territory_name is null. The territory gateway is already paused or resumed. The BrokerAdminClient does not have permission to modify the Broker. The Broker to which this client is connected is not a member of a territory. There is no gateway to the specified territory from this Broker. The gateway Broker does not support this feature.

webMethods Broker Administration Java API Programmers Guide Version 8.2

297

12 Java API Administration Reference

Possible Exceptions
BrokerQueueBrowserException

Meaning The gateway forwarding queue is locked by a queue browser.

setTerritoryGatewayRefuseAllUpdates
public void setTerritoryGatewayRefuseAllUpdates( String territory_name) boolean refuse_updates) throws BrokerException

territory_name refuse_updates

The name of the territory to which updates are refused. Specify whether the territory will refuse all updates from a neighboring territory connected by a gateway (true).

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. Possible Exceptions
BrokerInvalidClientException BrokerNoPermissionException BrokerNotInTerritoryException BrokerNullParameterException BrokerUnknownTerritoryException

Meaning The BrokerAdminClient has been destroyed or disconnected. The BrokerAdminClient does not have permission to browse the Broker. The Broker is not a member of a territory. The territory_name parameter is null. There is no gateway to the specified territory from this client's Broker.

See Also: BrokerAdminClient.getTerritoryGatewayRefuseAllUpdates setTerritoryGatewayRefuseEventTypeUpdates

public void setTerritoryGatewayRefuseEventTypeUpdates( String territory_name BrokerSharedEventTypeRefuseUpdateInfo[] infos) throws BrokerException

territory_name

The name of the territory for which updates made in a neighboring territory are refused.

298

webMethods Broker Administration Java API Programmers Guide Version 8.2

12 Java API Administration Reference

infos

Specifies information about whether events and updates for a document type in a neighboring territory are refused.

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. Possible Exceptions
BrokerInvalidClientException BrokerNoPermissionException BrokerNotInTerritoryException BrokerNullParameterException BrokerUnknownTerritoryException

Meaning The BrokerAdminClient has been destroyed or disconnected. The BrokerAdminClient does not have permission to browse the Broker. The Broker is not a member of a territory. The territory_name parameter is null. There is no gateway to the specified territory from this client's Broker.

See Also: BrokerAdminClient.getTerritoryGatewayRefuseEventTypeUpdates setTerritoryGatewaySecurity

void setTerritoryGatewaySecurity( String territory_name, int auth_type, int encrypt_level) throws BrokerException

territory_name auth_type encrypt_level

The name of the territory whose gateway security is to be set. The type of authentication to set for the gateway, specified as one of the AUTH_TYPE_* values defined by BrokerAdminClient. 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 Programmers Guide.

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.

webMethods Broker Administration Java API Programmers 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. Possible Exceptions
BrokerInvalidClientException BrokerNoPermissionException BrokerNotInTerritoryException BrokerNullParameterException BrokerOutOfRangeException BrokerUnknownTerritoryException

Meaning The BrokerAdminClient has been destroyed or disconnected. The BrokerAdminClient does not have permission to modify the Broker. The Broker to which this client is connected is not part of a territory. The territory_name parameter is null. The auth_type or encrypt_level parameter contains an invalid value. There is no gateway to the specified territory from this Broker.

See also BrokerAdminClient.getAllClusterGateways and BrokerAdminClient.getLocalClusterGateways setTerritoryGatewaySharedEventTypes

void setTerritoryGatewaySharedEventTypes( String territory_name, BrokerSharedEventTypeInfo infos[]) throws BrokerException

territory_name infos

The name of the territory whose shared event types are to be set. The shared event type information.

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 Programmers Guide for complete information on event filtering See BrokerSharedEventTypeInfo for more information.

300

webMethods Broker Administration Java API Programmers Guide Version 8.2

12 Java API Administration Reference

Possible Exceptions
BrokerInvalidClientException BrokerInvalidSubscriptionException BrokerInvalidTypeDefException

Meaning The BrokerAdminClient has been destroyed or disconnected A parse error was encountered in one of the elements contained in infos. One or more of the event types is incompatible with the type definition on the remote Broker. The client does not have permission to modify the Broker. The Broker to which this client is connected is not part of a territory. The gateway connection is currently not open. 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. An event type in infos does not have accept_subscribe permission, but has a nonempty subscription_filter. An element in infos does not exist on either Broker in the gateway. If this exception is thrown, no changes are applied. There is no gateway to the specified territory from the local Broker.

BrokerNoPermissionException BrokerNotInTerritoryException BrokerNotRunningException BrokerNullParameterException

BrokerOutOfRangeException

BrokerUnknownEventTypeException

BrokerUnknownTerritoryException

See Also: BrokerAdminClient.getTerritoryGatewaySharedEventTypes setTerritorySecurity

void setTerritorySecurity( int auth_type, int encrypt_level) throws BrokerException

auth_type encrypt_level

The type of authentication to set for the territory, specified as one of the AUTH_TYPE_* values defined by BrokerAdminClient. 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 Programmers Guide.

webMethods Broker Administration Java API Programmers 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. Possible Exceptions
BrokerInvalidClientException BrokerNoPermissionException BrokerNotInTerritoryException BrokerOutOfRangeException

Meaning The BrokerAdminClient has been destroyed or disconnected. The BrokerAdminClient does not have permission to modify the Broker. The Broker to which this client is connected is not part of a territory. The auth_type or encrypt_level parameter contains an invalid value.

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 Programmers Guide. The following table shows the BrokerTypeDef constants for each field type. BrokerTypeDef Data Members
short FIELD_TYPE_BOOLEAN short FIELD_TYPE_BYTE short FIELD_TYPE_CHAR short FIELD_TYPE_DATE short FIELD_TYPE_DOUBLE short FIELD_TYPE_FLOAT short FIELD_TYPE_INT

Description Represents a boolean. Represents a byte. Represents a char. Represents a BrokerDate. Represents a double. Represents a float. Represents a int.

302

webMethods Broker Administration Java API Programmers Guide Version 8.2

12 Java API Administration Reference

BrokerTypeDef Data Members

short FIELD_TYPE_LONG short FIELD_TYPE_SEQUENCE short FIELD_TYPE_SHORT short FIELD_TYPE_STRING short FIELD_TYPE_STRUCT short FIELD_TYPE_UNKNOWN

Description Represents a long. Represents a sequence field. Represents a short. Represents a string. Represents a structure field. Represents a unknown field type.

Storage Type
STORAGE_GUARANTEED

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

STORAGE_VOLATILE

Constructors
BrokerAdminTypeDef
BrokerAdminTypeDef( BrokerTypeDef normal_def) throws BrokerException

normal_def

The BrokerTypeDef that this object is to administer.

Creates a copy of a normal type definition. Possible Exceptions

BrokerNullParameterException

Meaning The parameter normal_def parameter is null.

BrokerAdminTypeDef
BrokerAdminTypeDef( BrokerAdminTypeDef type_def) throws BrokerException

type_def Copy constructor.

The object being copied.

webMethods Broker Administration Java API Programmers Guide Version 8.2

303

12 Java API Administration Reference

Possible Exceptions
BrokerNullParameterException

Meaning The parameter type_def parameter is null.

BrokerAdminTypeDef
BrokerAdminTypeDef( short type) throws BrokerException

type

The field type being created. You can use any of the values listed in the table in BrokerAdminTypeDef except FIELD_TYPE_EVENT.

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. Possible Exceptions
BrokerInvalidTypeException

Meaning The type is FIELD_TYPE_EVENT or an invalid value.

BrokerAdminTypeDef
BrokerAdminTypeDef( String type_name, short type) throws BrokerException

type_name type

The name of the type being created. The type being created. Must be either FIELD_TYPE_EVENT or FIELD_TYPE_STRUCT.

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 Programmers Guide. Possible Exceptions
BrokerInvalidEventTypeNameException BrokerInvalidTypeException BrokerNullParameterException

Meaning The type_name is invalid. The type is not FIELD_TYPE_EVENT or a FIELD_TYPE_STRUCT. The parameter type_name parameter is null and type is FIELD_TYPE_EVENT.

304

webMethods Broker Administration Java API Programmers Guide Version 8.2

12 Java API Administration Reference

Methods
clearField
void clearField( String field_name) throws BrokerException

field_name

The name of the event field to be removed from the definition.

Removes the specified field name from the event type definition. Possible Exceptions
BrokerFieldNotFoundException BrokerFieldTypeMismatchException BrokerInvalidFieldNameException BrokerInvalidTypeException BrokerNullParameterException

Meaning Specified field_name does not exist in the event. The field_name incorrectly accesses a type, such as using a subscript with a non-sequence field. The field_name is invalid. The field is not a field in a struct or event type. The field_name parameter is null.

See Also: BrokerAdminTypeDef.clearFields

clearFields
void clearFields()

Deletes all fields from the event type definition. Possible Exceptions
BrokerInvalidTypeException

Meaning This object is not a struct or event type.

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

webMethods Broker Administration Java API Programmers 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. Possible Exceptions
BrokerInvalidTypeException

Meaning This object's type is not FIELD_TYPE_EVENT.

See Also: BrokerAdminTypeDef.setDescription

getFieldDef
BrokerAdminTypeDef getFieldDef( String field_name) throws BrokerException

field_name

The name of the field whose definition is to be returned.

Returns a BrokerAdminTypeDef containing the field definition for the specified field name. Possible Exceptions
BrokerFieldNotFoundException BrokerFieldTypeMismatchException BrokerInvalidFieldNameException

Meaning Specified field_name does not exist in the event. The field_name incorrectly accesses a type, such as using a subscript with a non-sequence field. The parameter field_name not valid.

See Also: BrokerAdminTypeDef.getFieldNames, BrokerAdminTypeDef.getFieldType, BrokerAdminTypeDef.setFieldDef, and BrokerAdminTypeDef.setFieldType

getFieldNames
String[] getFieldNames( String field_name) throws BrokerException

306

webMethods Broker Administration Java API Programmers Guide Version 8.2

12 Java API Administration Reference

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.

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. Possible Exceptions
BrokerFieldNotFoundException BrokerFieldTypeMismatchException BrokerInvalidFieldNameException

Meaning Specified field_name does not exist in the event. The field_name incorrectly accesses a type, such as using a subscript with a non-sequence field. The field_name is invalid.

See Also: BrokerAdminTypeDef.getFieldDef and BrokerAdminTypeDef.getFieldType

getFieldType
short getFieldType( String field_name) throws BrokerException

field_name

If set to null, the event's type is returned. Otherwise, the type of the specified field is returned.

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. Possible Exceptions
BrokerFieldNotFoundException BrokerFieldTypeMismatchException BrokerInvalidFieldNameException

Meaning Specified field_name does not exist in the event. The field_name incorrectly accesses a type, such as using a subscript with a non-sequence field. The field_name is invalid.

See Also: BrokerAdminTypeDef.getFieldDef, BrokerAdminTypeDef.setFieldDef, and BrokerAdminTypeDef.setFieldType

getScopeTypeName
String getScopeTypeName()

Returns this event type's scope name.

webMethods Broker Administration Java API Programmers 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. Possible Exceptions
BrokerInvalidTypeException

Meaning The type of this object is not FIELD_TYPE_EVENT.

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. Possible Exceptions
BrokerInvalidTypeException

Meaning The type of this object is not FIELD_TYPE_EVENT.

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.

308

webMethods Broker Administration Java API Programmers 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

field_name index

The name of the field to be added or moved. The offset within the event where the field is to be positioned. The field will be inserted before the field with the specified index. The type definition for the field being added or moved.

field_def

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 Programmers 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. Possible Exceptions
BrokerFieldTypeMismatchException BrokerInvalidFieldNameException BrokerInvalidTypeException BrokerNullParameterException BrokerOutOfRangeException

Meaning The field_name incorrectly accesses a type, such as using a subscript with a non-sequence field. The field_name is invalid. The field's type is not FIELD_TYPE_EVENT or FIELD_TYPE_STRUCT. The field_def parameter is null. The index is less than zero.

See Also: BrokerAdminTypeDef.getFieldDef and BrokerAdminTypeDef.setFieldDef

isSystemDefined
boolean isSystemDefined()

webMethods Broker Administration Java API Programmers 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

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. An array of field names, specified in the order in which they are to appear in the field.

new_field_names

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. Possible Exceptions
BrokerFieldNotFoundException BrokerFieldTypeMismatchException BrokerInvalidFieldNameException BrokerInvalidTypeException BrokerNullParameterException

Meaning The specified field_name or any of the entries in new_field_names does not exist in the event. The field_name incorrectly accesses a type, such as using a subscript with a non-sequence field. The field_name is invalid. The field's type is not FIELD_TYPE_EVENT or FIELD_TYPE_STRUCT. The new_field_names parameter is null or one of its entries is null.

See Also: BrokerAdminTypeDef.getFieldNames

renameField
void renameField( String old_field_name, String new_field_name) throws BrokerException

old_field_name

The name of a field to be renamed.

310

webMethods Broker Administration Java API Programmers Guide Version 8.2

12 Java API Administration Reference

new_field_name

The new field name.

Renames the administrative type definition field specified by old_field_name to new_field_name. See the webMethods Broker Client Java API Programmers Guide for complete information on specifying field names. Note: For information on event field name restrictions, see the webMethods Broker Client Java API Programmers Guide. Possible Exceptions
BrokerFieldNotFoundException BrokerFieldTypeMismatchException

Meaning The specified old_field_name does not exist in the event. The old_field_name incorrectly accesses a type, such as using a subscript with a non-sequence field. The old_field_name or new_field_name is invalid. 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. The old_field_name or new_field_name parameter is null.

BrokerInvalidFieldNameException BrokerInvalidTypeException

BrokerNullParameterException

See Also: BrokerAdminTypeDef.clearField and BrokerAdminTypeDef.clearFields

setDescription
void setDescription( String description) throws BrokerException

description

The description to set for the event type definition.

Sets the description for the event type definition. Possible Exceptions
BrokerInvalidTypeException BrokerNullParameterException

Meaning This object's type is not FIELD_TYPE_EVENT. The description parameter is null.

See Also: BrokerAdminTypeDef.getDescription

webMethods Broker Administration Java API Programmers Guide Version 8.2

311

12 Java API Administration Reference

setFieldDef
void setFieldDef( String field_name, BrokerAdminTypeDef field_def) throws BrokerException

field_name field_def

The name of the field whose definition is being set. The new type definition for the field.

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 Programmers Guide. Possible Exceptions
BrokerFieldTypeMismatchException BrokerInvalidFieldNameException BrokerNullParameterException

Meaning The field_name incorrectly accesses a type, such as using a subscript with a non-sequence field. The field_name is invalid. The field_name or field_def parameter is null.

See Also: BrokerAdminTypeDef.getFieldDef, BrokerAdminTypeDef.orderFields, and BrokerAdminTypeDef.setFieldType

setFieldType
void setFieldType( String field_name, short field_type, String type_name) throws BrokerException

field_name field_type type_name

The name of the field whose definition is being set. The field's type, defined as one of the values shown in the table in BrokerAdminTypeDef. Currently not used and should be set to null.

Sets the type of the specified field_name. If the field does not exist in the event type, it is created. Possible Exceptions
BrokerFieldTypeMismatchException

Meaning The field_name incorrectly accesses a type, such as using a subscript with a non-sequence field.

312

webMethods Broker Administration Java API Programmers Guide Version 8.2

12 Java API Administration Reference

Possible Exceptions
BrokerInvalidFieldNameException BrokerInvalidTypeException BrokerNullParameterException

Meaning The field_name is invalid. An attempt was made to change a field's type to FIELD_TYPE_SEQUENCE. The field_name parameter is null.

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

storage_type

The new storage type for the event type definition. Must be one of the following values: BrokerTypeDef.STORAGE_GUARANTEED BrokerTypeDef.STORAGE_VOLATILE

Sets the storage type for the event type definition. Possible Exceptions
BrokerInvalidTypeException BrokerOutOfRangeException

Meaning This object's type is invalid. The storage_type parameter is invalid.

See Also: BrokerAdminTypeDef.getStorageType

setTimeToLive
void setTimeToLive( int time_to_live) throws BrokerException

webMethods Broker Administration Java API Programmers Guide Version 8.2

313

12 Java API Administration Reference

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.

Sets the number of seconds an event will be available after being published before it expires and is destroyed. Possible Exceptions
BrokerInvalidTypeException BrokerOutOfRangeException

Meaning This object's type not FIELD_TYPE_EVENT. The time_to_live parameter is less than zero.

See Also: BrokerAdminTypeDef.getTimeToLive

setTypeName
void setTypeName( String type_name) throws BrokerException

type_name

The new, fully-qualified name for the event type.

Sets the fully-qualified name for the event type. Note: For information on event field name restrictions, see the webMethods Broker Client Java API Programmers Guide. Possible Exceptions
BrokerInvalidEventTypeNameException BrokerInvalidTypeException BrokerNullParameterException

Meaning This object's type not FIELD_TYPE_EVENT. The type is not FIELD_TYPE_STRUCT or
FIELD_TYPE_EVENT

The type_name parameter is null.

See Also: BrokerAdminTypeDef.getTypeName.

toString
String toString()

Returns a string containing the type definition administration object in a human-readable format.

314

webMethods Broker Administration Java API Programmers Guide Version 8.2

12 Java API Administration Reference

toString
String toString( int indent_level

indent_level

The number of 4-space indentations that should be generated in the output.

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 clients basic authentication username. For SSL protocol, contains the clients distinguished name.

authenticator
String authenticator

For basic authentication protocol, contains the authenticator alias. For SSL protocol, contains the issuers distinguished name.

Constructors
BrokerAuthInfo
BrokerAuthInfo()

Creates an empty BrokerAuthInfo object.

webMethods Broker Administration Java API Programmers Guide Version 8.2

315

12 Java API Administration Reference

BrokerAuthInfo
BrokerAuthInfo( String username, String authenticator)

username authenticator

The Broker clients username or distinguished name. The authenticator alias or the issuers distinguished name.

Creates a BrokerAuthInfo object, initialized with the specified parameters.

BrokerAuthInfo
public BrokerAuthInfo( final BrokerAuthInfo source)

source

An existing instance of the BrokerAuthInfo object.

Creates a BrokerAuthInfo object initialized with the data from the source object.

Methods
getAuthenticator
public String getAuthenticator()

Returns the client programs authenticator alias for a basic authentication connection, or returns the issuers distinguished name for an SSL connection.

getUserName
public String getUserName()

Returns the client programs authentication username for a basic authentication connection, or returns the client programs distinguished name for an SSL connection.

setAuthenticator
public void setAuthenticator( final String authenticator)

Sets the client programs authenticator alias for a basic authentication connection, or sets the issuers distinguished name for an SSL connection.

setUserName
public void setUserName( final String userName)

Sets the client programs authentication username for a basic authentication connection, or sets the client programs distinguished name for an SSL connection.

316

webMethods Broker Administration Java API Programmers 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)

indent_level

The number of four-space indentations that should be generated in the output.

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.

webMethods Broker Administration Java API Programmers 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 Programmers 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 Programmers 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)

new_name new_description new_life_cycle

The name for the client group. The client group's description. 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. 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.

new_storage_type

Creates a BrokerClientGroupInfo object, initialized with the specified name, description, lifecycle, and event queue storage type. Note: For information on client group name restrictions, see the webMethods Broker Client Java API Programmers Guide.

webMethods Broker Administration Java API Programmers 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)

indent_level

The number of 4-space indentations that should be generated in the output.

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

320

webMethods Broker Administration Java API Programmers 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 Programmers 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 Programmers 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)

new_client_id new_client_group new_app_name new_can_share_state

The Broker client's identifier. The client group with which the Broker client is associated. The Broker client's application name. 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. 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. The highest publish sequence number for this client. Should be set to zero or a positive number.

new_state_share_limit

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

322

webMethods Broker Administration Java API Programmers 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)

indent_level

The number of 4-space indentations that should be generated in the output.

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.

webMethods Broker Administration Java API Programmers Guide Version 8.2

323

12 Java API Administration Reference

Possible Exceptions
BrokerTimeoutException BrokerOutOfRangeException BrokerClientQueueBrowserException BrokerClientQueueBrowserException

Meaning The timeout is reached before any events arrive. The max_events or msecs parameter is less than zero. The queue browser is invalid. The event at the last cursor position was removed. Reset the cursor to a valid position before attempting a browse operation. The client queue is busy; retry the operation later.

BrokerClientQueueBrowserException

closeQueueBrowser
BrokerClientQueueBrowserInfo getBrowserInfo() throws BrokerException

Gets information on the current queue browser. Returns a BrokerClientQueueBrowser object. Possible Exceptions
BrokerClientQueueBrowserException

Meaning The queue browser is invalid.

getBrowserInfo
BrokerClientQueueBrowserInfo getBrowserInfo() throws BrokerException

Gets information on the current queue browser. Returns a BrokerClientQueueBrowser object. Possible Exceptions
BrokerClientQueueBrowserException

Meaning The queue browser is invalid.

getFilters
void getFilters() throws BrokerException

Returns the filters set on the queue browser. Possible Exceptions

BrokerClientQueueBrowserException

Meaning The queue browser is invalid.

324

webMethods Broker Administration Java API Programmers 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. Possible Exceptions
BrokerClientQueueBrowserException

Meaning The queue browser is invalid.

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. Possible Exceptions
BrokerClientQueueBrowserException BrokerFilterParseException BrokerInvalidFilterException BrokerNullParameterException BrokerUnknownEventTypeException

Meaning The queue browser is invalid. An error occurred while parsing the filter expression The specified filter expression on the filter object is invalid. The filter parameter is null or the filter expression on the BrokerFilterDescriptor is null. The specified event type on the filter object does not exist on the Broker.

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
BrokerClientQueueBrowserException

Meaning The queue browser is invalid.

webMethods Broker Administration Java API Programmers Guide Version 8.2

325

12 Java API Administration Reference

Possible Exceptions
BrokerFilterParseException BrokerInvalidFilterException BrokerNullParameterException BrokerUnknownEventTypeException

Meaning An error occurred while parsing the filter expression The specified filter expression on the filter object is invalid. The filters parameter is null or the filter expression on the BrokerFilterDescriptor is null. The specified event type on the filter object does not exist on the Broker.

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". Possible Exceptions
BrokerClientQueueBrowserException

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

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

326

webMethods Broker Administration Java API Programmers 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 Programmers 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 Programmers Guide.

328

webMethods Broker Administration Java API Programmers 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 Programmers 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 Programmers 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)

new_session_id new_connection_id new_ip_address new_port new_encrypt_protocol new_encrypt_version new_encyrpt_level new_auth_protocol new_auth_version BrokerSSLCentificate new_connect_time new_create_time new_last_activity_time

The Broker client's identifier. The Broker client connection identifier. The Broker client's IP address. The port number for the session. The encryption protocol for the session. The encryption version for the session. The level of encryption for the session. The authentication protocol for the session. The authentication version for the session. The SSL certificate for the session. The time the client connected to the Broker. The time the client session was created. The time data was last sent across the connection between the client and the Broker.

Creates a BrokerClientSession object, initialized with the specified parameters.

Methods
toString
String toString()

Returns a human-readable string containing the client session information.

330

webMethods Broker Administration Java API Programmers 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 Programmers 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 Programmers 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 Programmers Guide Version 8.2

12 Java API Administration Reference

toString
String toString( int indent_level, boolean hide_gateway_broker, boolean hide_accessible_clusters)

indent_level hide_gateway_broker hide_accessible_clusters

The number of 4-character spaces to use for indentation. If set to true, the gateway Broker's host and name as well as the is_local information, will be omitted. If set to true, the accessible_clusters and is_complete information will be omitted.

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

isLocalPublish
boolean isLocalPublish

webMethods Broker Administration Java API Programmers 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)

indent_level

The number of 4-character spaces to use for indentation.

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.

334

webMethods Broker Administration Java API Programmers 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 Programmers Guide Version 8.2

335

12 Java API Administration Reference

BrokerCompleteBroker
BrokerCompleteBroker( BrokerInfo info)

info

The BrokerInfo object used to initialize this object.

Creates a BrokerCompleteBroker object and initializes it from a BrokerInfo object.

Methods
deepRefresh
void deepRefresh( BrokerAdminClient client) throws BrokerException

client

The administrative client to be used to refresh this object.

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. Possible Exceptions
BrokerInvalidClientException BrokerNullParameterException

Meaning The BrokerAdminClient has been destroyed or disconnected. The client parameter is null.

See Also: BrokerCompleteBroker.refresh

deepRetrieve
static BrokerCompleteBroker deepRetrieve( BrokerAdminClient client) throws BrokerException

client

The administrative client to be used to retrieve the Broker information.

336

webMethods Broker Administration Java API Programmers 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. Possible Exceptions
BrokerInvalidClientException BrokerNullParameterException

Meaning The BrokerAdminClient has been destroyed or disconnected. The client parameter is null.

See Also: BrokerCompleteBroker.retrieve

deepStore
void deepStore( BrokerAdminClient client) throws BrokerException

client

The administrative client to be used to store the Broker information.

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
BrokerInvalidClientException BrokerInvalidClientGroupNameException BrokerNoPermissionException BrokerNullParameterException BrokerOutOfRangeException

Meaning The BrokerAdminClient has been destroyed or disconnected. Specified client group name is not valid. The client does not have permission to change the Broker's configuration. The client parameter is null. A client group contained an invalid value for its life cycle or storage parameter type.

webMethods Broker Administration Java API Programmers Guide Version 8.2

337

12 Java API Administration Reference

Possible Exceptions
BrokerUnknownEventTypeException

Meaning A client group contains an event type in its can_publish or can_subscribe list that does not exist on the Broker.

See Also: BrokerCompleteBroker.store

refresh
void refresh( BrokerAdminClient client) throws BrokerException

client

The administrative client to be used to refresh this object.

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. Possible Exceptions
BrokerInvalidClientException BrokerNullParameterException

Meaning The BrokerAdminClient has been destroyed or disconnected. The client parameter is null.

See Also: BrokerCompleteBroker.deepRefresh

retrieve
static BrokerCompleteBroker retrieve( BrokerAdminClient client) throws BrokerException

client

The administrative client to be used to retrieve contents for this object.

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.

338

webMethods Broker Administration Java API Programmers Guide Version 8.2

12 Java API Administration Reference

Possible Exceptions
BrokerInvalidClientException BrokerNullParameterException

Meaning The BrokerAdminClient has been destroyed or disconnected. The client parameter is null.

See Also: BrokerCompleteBroker.deepRetrieve

store
void deepStore( BrokerAdminClient client) throws BrokerException

client

The administrative client to be used to store the Broker information.

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. Possible Exceptions
BrokerInvalidClientException BrokerNoPermissionException BrokerNullParameterException

Meaning The BrokerAdminClient has been destroyed or disconnected. The client does not have permission to change the Broker's configuration. The client parameter is null.

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.

webMethods Broker Administration Java API Programmers Guide Version 8.2

339

12 Java API Administration Reference

toString
String toString( int indent_level) throws BrokerException

indent_level

The number of 4-character spaces to use for indentation.

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
BrokerOutOfRangeException

Meaning The indent_level parameter is less than 0.

write
void write( Writer writer, int indent_level) throws BrokerException, IOException

writer indent_level

The file where the data is to be written. The number of 4-character spaces to use for indentation.

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. Possible Exceptions
IOException BrokerNullParameterException BrokerOutOfRangeException

Meaning There was an error writing the data to the file. The writer parameter is null. The indent_level parameter is less than 0.

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.

340

webMethods Broker Administration Java API Programmers 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 Programmers 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)

info

The object being copied.

This is a copy constructor.

webMethods Broker Administration Java API Programmers Guide Version 8.2

341

12 Java API Administration Reference

Methods
refresh
void refresh( BrokerAdminClient client) throws BrokerException

client

The administrative client to be used to refresh this object.

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. Possible Exceptions
BrokerInvalidClientException BrokerNullParameterException BrokerNoPermissionException BrokerUnknownClientIdException

Meaning The BrokerAdminClient has been destroyed or disconnected. The client parameter is null. The client does not have permission to browse the information. The client ID specified in the client_info.client_id variable does not exist on the Broker.

See Also: BrokerCompleteClient.retrieve

retrieve
static BrokerCompleteBroker retrieve( BrokerAdminClient client) throws BrokerException

client

The administrative client to be used to retrieve contents for this object.

Returns a BrokerCompleteClient object containing information on the specified client. Possible Exceptions
BrokerInvalidClientException BrokerNullParameterException BrokerNoPermissionException

Meaning The BrokerAdminClient has been destroyed or disconnected. The client parameter is null. The client does not have permission to browse the information.

342

webMethods Broker Administration Java API Programmers Guide Version 8.2

12 Java API Administration Reference

Possible Exceptions
BrokerUnknownClientIdException

Meaning The client id specified in the client_info.client_id variable does not exist on the Broker.

See Also: BrokerCompleteClient.refresh

store
void deepStore( BrokerAdminClient client) throws BrokerException

client

The administrative client to be used to store the Broker information.

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. Possible Exceptions
BrokerInvalidClientException BrokerInvalidSubscriptionException

Meaning The BrokerAdminClient has been destroyed or disconnected. The filter string in a subscription in the subscriptions variable contains a parse error.

webMethods Broker Administration Java API Programmers Guide Version 8.2

343

12 Java API Administration Reference

Possible Exceptions
BrokerNoPermissionException BrokerNullParameterException BrokerOutOfRangeException

Meaning The client does not have permission to change the Broker's configuration. The client parameter is null. A sub_id element in a subscription contained in subscriptions is less than zero or the state_share_limit element is less than -1. The client group in the client_info.client_group variable does not exist on the Broker. 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.

BrokerUnknownClientGroupException

BrokerUnknownEventTypeException

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

indent_level

The number of 4-character spaces to use for indentation.

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.

344

webMethods Broker Administration Java API Programmers Guide Version 8.2

12 Java API Administration Reference

Possible Exceptions
BrokerOutOfRangeException

Meaning The indent_level parameter is less than 0.

See Also: BrokerCompleteClient.write.

write
void write( Writer writer, int indent_level) throws BrokerException, IOException

writer indent_level

The file where the data is to be written. The number of 4-character spaces to use for indentation.

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. Possible Exceptions
IOException BrokerNullParameterException BrokerOutOfRangeException

Meaning There was an error writing the data to the file. The writer parameter is null. The indent_level parameter is less than 0.

See Also: BrokerCompleteClient.toString.

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

webMethods Broker Administration Java API Programmers 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)

info

The BrokerInfo object used to initialize this object.

Creates a BrokerCompleteBroker object and initializes it from a BrokerClientGroupInfo object.

346

webMethods Broker Administration Java API Programmers Guide Version 8.2

12 Java API Administration Reference

Methods
refresh
void refresh( BrokerAdminClient client) throws BrokerException

client

The administrative client to be used to refresh this object.

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. Possible Exceptions
BrokerInvalidClientException BrokerInvalidClientGroupNameException BrokerNoPermissionException BrokerNullParameterException

Meaning The BrokerAdminClient has been destroyed or disconnected. The specified client group name is not valid. The client does not have permission to read the client group configuration. The client parameter, the data member client_group_info, or the variable client_group_info.name is null. The client group does not exist on the Broker.

BrokerUnknownClientGroupException

See Also: BrokerCompleteClientGroup.retrieve

retrieve
static BrokerCompleteClientGroup retrieve( BrokerAdminClient client, String client_group_name) throws BrokerException

client client_group_name

The administrative client to be used to retrieve contents for this object. The name of the client group whose information is to be returned.

Retrieves the information about a specified client group, using the specified administrative client.

webMethods Broker Administration Java API Programmers 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. Possible Exceptions
BrokerInvalidClientException BrokerNoPermissionException BrokerNullParameterException BrokerUnknownClientGroupException

Meaning The BrokerAdminClient has been destroyed or disconnected. The client does not have permission to read the client group configuration. The client or client_group_name parameter is null. The client_group_name does not exist on the Broker.

See Also: BrokerCompleteClientGroup.refresh

store
void store( BrokerAdminClient client) throws BrokerException

client

The administrative client to be used to store this object.

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
BrokerInvalidClientException

Meaning The BrokerAdminClient has been destroyed or disconnected.

348

webMethods Broker Administration Java API Programmers Guide Version 8.2

12 Java API Administration Reference

Possible Exceptions
BrokerInvalidClientGroupNameException BrokerNoPermissionException BrokerNullParameterException

Meaning The specified client group name is not valid. The client does not have permission to read the client group configuration. The client parameter, the data member client_group_info, or the variable client_group_info.name is null.l The client group does not exist on the Broker.

BrokerUnknownClientGroupException

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

indent_level

The number of 4-character spaces to use for indentation.

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

writer indent_level

The file where the data is to be written. The number of 4-character spaces to use for indentation.

webMethods Broker Administration Java API Programmers 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. Possible Exceptions
IOException BrokerNullParameterException BrokerOutOfRangeException

Meaning There was an error writing the data to the file. The writer parameter is null. The indent_level parameter is less than 0.

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

350

webMethods Broker Administration Java API Programmers 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

reader

The file from which the configuration is to be created.

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. Possible Exceptions
IOException BrokerInputParseException BrokerNullParameterException

Meaning There was an error reading data from the file. There was a parse error in the input data. The reader parameter is null.

See Also: BrokerCompleteCollection.readFile

webMethods Broker Administration Java API Programmers Guide Version 8.2

351

12 Java API Administration Reference

readFile
static BrokerCompleteCollection readFile( String filename) throws BrokerException, IOException

reader

The file from which the configuration is to be created.

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. Possible Exceptions
IOException BrokerInputParseException BrokerNullParameterException

Meaning There was an error reading data from the file. There was a parse error in the input data. The filename parameter is null.

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

indent_level

The number of 4-character spaces to use for indentation.

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.

352

webMethods Broker Administration Java API Programmers Guide Version 8.2

12 Java API Administration Reference

write
void write( Writer writer, int indent_level) throws BrokerException, IOException

writer indent_level

The file where the data is to be written. The number of 4-character spaces to use for indentation.

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. Possible Exceptions
IOException BrokerNullParameterException BrokerOutOfRangeException

Meaning There was an error writing the data to the file. The writer parameter is null. The indent_level parameter is less than 0.

See Also: BrokerCompleteCollection.writeVersionNumber

writeVersionNumber
static void writeVersionNumber( Writer writer, int indent_level) throws BrokerException, IOException

writer indent_level

The file where the version number is to be written. The number of 4-character spaces to use for indentation.

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.

webMethods Broker Administration Java API Programmers 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. Possible Exceptions
IOException BrokerNullParameterException BrokerOutOfRangeException

Meaning There was an error writing the data to the file. The writer parameter is null. The indent_level parameter is less than 0.

See Also: BrokerCompleteBroker.write, BrokerCompleteClientGroup.write, BrokerCompleteEventType.write, and BrokerCompleteServer.write

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

354

webMethods Broker Administration Java API Programmers Guide Version 8.2

12 Java API Administration Reference

Constructors
BrokerCompleteEventType
BrokerCompleteEventType()

Creates an empty BrokerCompleteEventType object.

BrokerCompleteEventType
BrokerCompleteEventType(BrokerAdminTypeDef type_def

type_def

The BrokerAdminTypeDef used to initialize this object.

Creates a BrokerCompleteEventType object, initialized from the specified administrative type definition object.

Methods
refresh
void refresh( BrokerAdminClient client) throws BrokerException

client

The administrative client to be used to refresh this object.

Refreshes this object's event type information, using the specified administrative Broker client. The data member type_def must be set. Possible Exceptions
BrokerInvalidClientException BrokerNoPermissionException BrokerNullParameterException

Meaning The BrokerAdminClient has been destroyed or disconnected. The client does not have permission to read the event type configuration. The client parameter or the data member type_def is null, or the type_def has a null event type name. The event type contained in the object specified by type_def not exist on the Broker.

BrokerUnknownEventTypeException

See Also: BrokerCompleteEventType.retrieve

webMethods Broker Administration Java API Programmers Guide Version 8.2

355

12 Java API Administration Reference

retrieve
static BrokerCompleteEventType retrieve( BrokerAdminClient client, String event_type_name) throws BrokerException

client event_type_name

The administrative client to be used to retrieve contents for this object. The name of the client group whose information is to be returned.

Retrieves the information about a specified event type, using the specified administrative client. Possible Exceptions
BrokerInvalidClientException BrokerNoPermissionException BrokerNullParameterException BrokerUnknownEventTypeException

Meaning The BrokerAdminClient has been destroyed or disconnected. The client does not have permission to read the event type configuration. The client or event_type_name parameter is null. The event_type_name does not exist on the Broker.

See Also: BrokerCompleteEventType.refresh

store
void store( BrokerAdminClient client) throws BrokerException

client

The administrative client to be used to store this object.

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.

356

webMethods Broker Administration Java API Programmers 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, preexisting infosets on the Broker will not be deleted. If an exception is thrown, the Broker will not have been updated. Possible Exceptions
BrokerInvalidClientException BrokerInvalidClientGroupNameException BrokerNoPermissionException BrokerNullParameterException

Meaning The BrokerAdminClient has been destroyed or disconnected. The specified client group name is not valid. The client does not have permission to read the client group configuration. The client parameter, the data member client_group_info, or the variable client_group_info.name is null.l The client group does not exist on the Broker.

BrokerUnknownClientGroupException

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

indent_level

The number of 4-character spaces to use for indentation.

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.

webMethods Broker Administration Java API Programmers Guide Version 8.2

357

12 Java API Administration Reference

write
void write( Writer writer, int indent_level) throws BrokerException, IOException

writer indent_level

The file where the data is to be written. The number of 4-character spaces to use for indentation.

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. Possible Exceptions
IOException BrokerNullParameterException BrokerOutOfRangeException

Meaning There was an error writing the data to the file. The writer parameter is null. The indent_level parameter is less than 0.

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.

358

webMethods Broker Administration Java API Programmers 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 Programmers Guide Version 8.2

359

12 Java API Administration Reference

String app_name, BrokerConnectionDescriptor desc) throws BrokerException

client client_id

The administrative client to be used to refresh this object. 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 destroyon-disconnect. See the webMethods Broker Client Java API Programmers Guide for more information on client identifiers. The name of the client group for the new Broker client. Client groups are discussed in Administering webMethods Broker. The name of the application that will contain the new Broker client. 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.

client_group app_name desc

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. Possible Exceptions
BrokerInvalidClientException BrokerNullParameterException

Meaning The BrokerAdminClient has been destroyed or disconnected. The client parameter is null.

See Also: BrokerCompleteServer.refresh

deepRetrieve
static BrokerCompleteServer deepRetrieve( BrokerAdminClient client) String client_id, String client_group, String app_name, BrokerConnectionDescriptor desc) throws BrokerException

360

webMethods Broker Administration Java API Programmers Guide Version 8.2

12 Java API Administration Reference

client client_id

The administrative client to be used to retrieve contents for this object. 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 destroyon-disconnect. See the webMethods Broker Client Java API Programmers Guide for more information on client identifiers. The name of the client group for the new Broker client. Client groups are discussed in Administering webMethods Broker. The name of the application that will contain the new Broker client. 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.

client_group app_name desc

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. Possible Exceptions
BrokerInvalidClientException BrokerNullParameterException

Meaning The BrokerAdminClient has been destroyed or disconnected. The client parameter is null.

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 store this object.

webMethods Broker Administration Java API Programmers Guide Version 8.2

361

12 Java API Administration Reference

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 destroyon-disconnect. See the webMethods Broker Client Java API Programmers Guide for more information on client identifiers. The name of the client group for the new Broker client. Client groups are discussed in Administering webMethods Broker. The name of the application that will contain the new Broker client. 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.

client_group app_name desc

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.

362

webMethods Broker Administration Java API Programmers Guide Version 8.2

12 Java API Administration Reference

Possible Exceptions
BrokerInvalidClientException BrokerNoPermissionException BrokerNullParameterException

Meaning The BrokerAdminClient has been destroyed or disconnected. The client does not have permission to change the Broker's configuration. client, client_group, or app_name parameter is null.

See Also: BrokerCompleteServer.store

refresh
void refresh( BrokerAdminClient client) throws BrokerException

client

The administrative client to be used to refresh this object.

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. Possible Exceptions
BrokerInvalidClientException BrokerNullParameterException

Meaning The BrokerAdminClient has been destroyed or disconnected. The client parameter is null.

See Also: BrokerCompleteServer.deepRefresh

retrieve
static BrokerCompleteServer retrieve( BrokerAdminClient client) throws BrokerException

client

The administrative client to be used to retrieve contents for this object.

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.

webMethods Broker Administration Java API Programmers Guide Version 8.2

363

12 Java API Administration Reference

Possible Exceptions
BrokerInvalidClientException BrokerNullParameterException

Meaning The BrokerAdminClient has been destroyed or disconnected. The client parameter is null.

See Also: BrokerCompleteServer.deepRetrieve

store
void store( BrokerAdminClient client) throws BrokerException

client

The administrative client to be used to store the Broker information.

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. Possible Exceptions
BrokerInvalidClientException BrokerNoPermissionException BrokerNullParameterException

Meaning The BrokerAdminClient has been destroyed or disconnected. The client does not have permission to change the Broker's configuration. The client parameter is null.

See Also: BrokerCompleteServer.deepStore

364

webMethods Broker Administration Java API Programmers 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

indent_level

The number of 4-character spaces to use for indentation.

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
BrokerOutOfRangeException

Meaning The indent_level parameter is less than 0.

write
void write( Writer writer, int indent_level) throws BrokerException, IOException

writer indent_level

The file where the data is to be written. The number of 4-character spaces to use for indentation.

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. Possible Exceptions
IOException BrokerNullParameterException BrokerOutOfRangeException

Meaning There was an error writing the data to the file. The writer parameter is null. The indent_level parameter is less than 0.

webMethods Broker Administration Java API Programmers 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)

info

The territory information to set in the newly created object.

Creates a territory object, setting the info variable in the process.

366

webMethods Broker Administration Java API Programmers Guide Version 8.2

12 Java API Administration Reference

Methods
refresh
void refresh( BrokerAdminClient client) throws BrokerException

client

The administrative client to be used to refresh this object.

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. Possible Exceptions
BrokerInvalidClientException BrokerNullParameterException

Meaning The BrokerAdminClient has been destroyed or disconnected. The client parameter is null.

See Also: BrokerCompleteTerritory.retrieve

retrieve
static BrokerCompleteTerritory retrieve( BrokerAdminClient client) throws BrokerException

client

The administrative client to be used to retrieve contents for this object.

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. Possible Exceptions
BrokerInvalidClientException BrokerNullParameterException

Meaning The BrokerAdminClient has been destroyed or disconnected. The client parameter is null.

See Also: BrokerCompleteTerritory.store

webMethods Broker Administration Java API Programmers Guide Version 8.2

367

12 Java API Administration Reference

store
void store( BrokerAdminClient client) throws BrokerException

client

The administrative client to be used to store the Broker territory information.

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. Possible Exceptions
BrokerInvalidAccessListException BrokerInvalidClientException BrokerNullParameterException

Meaning The acl variable does not contain a valid access control list. The BrokerAdminClient has been destroyed or disconnected. The client parameter is null or the variable info or info.territory_name are null

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

368

webMethods Broker Administration Java API Programmers Guide Version 8.2

12 Java API Administration Reference

indent_level

The number of 4-character spaces to use for indentation.

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
BrokerOutOfRangeException

Meaning The indent_level parameter is less than 0.

write
void write( Writer writer, int indent_level) throws BrokerException, IOException

writer indent_level

The file where the data is to be written. The number of 4-character spaces to use for indentation.

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. Possible Exceptions
IOException BrokerNullParameterException BrokerOutOfRangeException

Meaning There was an error writing the data to the file. The writer parameter is null. The indent_level parameter is less than 0.

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.

webMethods Broker Administration Java API Programmers 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)

info

The gateway information to set in the newly created object.

Creates a territory gateway object, setting the info variable in the process.

370

webMethods Broker Administration Java API Programmers Guide Version 8.2

12 Java API Administration Reference

Methods
refresh
void refresh( BrokerAdminClient client) throws BrokerException

client

The administrative client to be used to refresh this object.

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. Possible Exceptions
BrokerInvalidClientException BrokerNotInTerritory BrokerNullParameterException BrokerUnknownTerritoryException

Meaning The BrokerAdminClient has been destroyed or disconnected. The Broker to which client is connected is not part of a territory. The client parameter is null or the variable info or info.remote_territory_name is null. There is no gateway to the specified territory from this Broker.

See Also: BrokerCompleteTerritoryGateway.retrieve

retrieve
static BrokerCompleteTerritoryGateway retrieve( BrokerAdminClient client) throws BrokerException

client

The administrative client to be used to retrieve contents for this object.

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. Possible Exceptions
BrokerInvalidClientException BrokerNotInTerritory

Meaning The BrokerAdminClient has been destroyed or disconnected. The Broker to which client is connected is not part of a territory.

webMethods Broker Administration Java API Programmers Guide Version 8.2

371

12 Java API Administration Reference

Possible Exceptions
BrokerNullParameterException BrokerUnknownTerritoryException

Meaning The client parameter is null. There is no gateway to the specified territory from this Broker.

See Also: BrokerCompleteTerritoryGateway.store

store
void store( BrokerAdminClient client) throws BrokerException

client

The administrative client to be used to store the Broker territory information.

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.

372

webMethods Broker Administration Java API Programmers Guide Version 8.2

12 Java API Administration Reference

Possible Exceptions
BrokerInvalidAccessListException BrokerInvalidClientException BrokerNullParameterException BrokerOutOfRangeException

Meaning The acl variable does not contain a valid access control list. The BrokerAdminClient has been destroyed or disconnected. The client parameter is null. 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. The other half of the gateway has not been established and the remote Broker could not be found.

BrokerUnknownBrokerNameException

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

indent_level

The number of 4-character spaces to use for indentation.

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
BrokerOutOfRangeException

Meaning The indent_level parameter is less than 0.

webMethods Broker Administration Java API Programmers Guide Version 8.2

373

12 Java API Administration Reference

write
void write( Writer writer, int indent_level) throws BrokerException, IOException

writer indent_level

The file where the data is to be written. The number of 4-character spaces to use for indentation.

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. Possible Exceptions
IOException BrokerNullParameterException BrokerOutOfRangeException

Meaning There was an error writing the data to the file. The writer parameter is null. The indent_level parameter is less than 0.

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.

374

webMethods Broker Administration Java API Programmers 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)

event_type_name filter_expr filter

Document name Expression

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.

BrokerForwardQueueBrowser
class 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:

webMethods Broker Administration Java API Programmers 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. Possible Exceptions
BrokerTimeoutException BrokerOutOfRangeException BrokerQueueBrowserException BrokerQueueBrowserException

Meaning The timeout is reached before an event arrives. The max_events or msecs parameter is less than zero. The queue browser is invalid. The event at the last cursor position was removed. Reset the cursor to a valid position before attempting a browse operation. The queue is busy; retry the operation later. 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. The client has been destroyed or is disconnected.

BrokerQueueBrowserException BrokerQueueBrowserException

BrokerInvalidClientException

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. Possible Exceptions
BrokerQueueBrowserException

Meaning The queue browser is invalid.

getFilters
void getFilters() throws BrokerException

376

webMethods Broker Administration Java API Programmers Guide Version 8.2

12 Java API Administration Reference

Returns the filters set on the forwarding queue browser. Possible Exceptions
BrokerQueueBrowserException

Meaning The queue browser is invalid.

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. Possible Exceptions
BrokerQueueBrowserException

Meaning The queue browser is invalid.

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. Possible Exceptions
BrokerQueueBrowserException BrokerFilterParseException BrokerInvalidFilterException BrokerNullParameterException BrokerUnknownEventTypeException

Meaning The queue browser is invalid. An error occurred while parsing the filter expression The specified filter expression on the filter object is invalid. The filter parameter is null or the filter expression on the BrokerFilterDescriptor is null. The specified event type on the filter object does not exist on the Broker.

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.

webMethods Broker Administration Java API Programmers Guide Version 8.2

377

12 Java API Administration Reference

Possible Exceptions
BrokerQueueBrowserException BrokerFilterParseException BrokerInvalidFilterException BrokerNullParameterException BrokerUnknownEventTypeException

Meaning The queue browser is invalid. An error occurred while parsing the filter expression The specified filter expression on the filter object is invalid. The filters parameter is null or the filter expression on the BrokerFilterDescriptor is null. The specified event type on the filter object does not exist on the Broker.

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

378

webMethods Broker Administration Java API Programmers 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)

territory host name description

The Broker's territory. The Broker's host name. The Broker's name. The Broker's 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 Programmers Guide.

BrokerJoinFailureInfo
class BrokerJoinFailureInfo extends java.lang.Object

webMethods Broker Administration Java API Programmers 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.

Constructors
BrokerJoinFailure()

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 Programmers 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. Possible Exceptions
BrokerClientQueueBrowserException BrokerClientQueueBrowserException

Meaning The queue browser is invalid. A receipt sequence number of value zero is specified, which is not a valid receipt sequence number. The client queue is busy; retry the operation. No event was found on the client queue for one or more of the specified receipt sequence numbers. The seqns parameter is null or of array length zero. A duplicate sequence number is found on the array.

BrokerClientQueueBrowserException BrokerInvalidSequenceNumberException

BrokerNullParameterException BrokerOutOfRangeException

insertEventsAtHead
void insertEventsAtHead( BrokerEvent[] events) throws BrokerException

Inserts events into the client queue at the head position (queue position of zero). Possible Exceptions
BrokerClientQueueBrowserException BrokerInvalidEventException BrokerNoPermissionException

Meaning The queue browser is invalid. One or more of the specified event is invalid. The target client queue does not have permission to subscribe to one or more of the specified events. The events parameter is null or of array length zero or one of the array element is null.

BrokerNullParameterException

insertEventsAtTail
void insertEventsAtTail( BrokerEvent[] events) throws BrokerException

webMethods Broker Administration Java API Programmers 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"). Possible Exceptions
BrokerClientQueueBrowserException BrokerInvalidEventException BrokerNoPermissionException

Meaning The queue browser is invalid. One or more of the specified event is invalid. The target client does not have permission to subscribe to one or more of the specified events. The events parameter is null or of array length zero or one of the array element is null.

BrokerNullParameterException

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

Meaning The queue browser is invalid. A receipt sequence number of value zero is specified, which is not a valid receipt sequence number. The client queue is busy; retry the operation. The storage types of replaced and replacing events do not match. 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. No event was found on the client queue for one or more of the specified receipt sequence numbers. The seqns or the events parameter is null or of array length zero.

BrokerClientQueueBrowserException BrokerClientQueueBrowserException BrokerClientQueueBrowserException

BrokerInvalidSequenceNumberException

BrokerNullParameterException

382

webMethods Broker Administration Java API Programmers Guide Version 8.2

12 Java API Administration Reference

Possible Exceptions
BrokerOutOfRangeException

Meaning A duplicate sequence number is found on the array

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. Possible Exceptions
BrokerQueueBrowserException BrokerQueueBrowserException

Meaning The queue browser is invalid. A receipt sequence number of value zero is specified, which is not a valid receipt sequence number. The forwarding queue is busy; retry the operation. No event was found on the forwarding queue for one or more of the specified receipt sequence numbers. The seqns parameter is null or of array length zero. A duplicate sequence number is found on the array.

BrokerQueueBrowserException BrokerInvalidSequenceNumberException

BrokerNullParameterException BrokerOutOfRangeException

webMethods Broker Administration Java API Programmers 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"). Possible Exceptions
BrokerQueueBrowserException BrokerInvalidEventException BrokerNullParameterException

Meaning The queue browser is invalid. One or more of the specified events is invalid. The events parameter is null or of array length zero or one of the array element is null.

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

Meaning The queue browser is invalid. A receipt sequence number of value zero is specified, which is not a valid receipt sequence number. The queue is busy; retry the operation. The storage types of replaced and replacing events do not match. The event cannot be modified as it has already been retrieved and is not yet acknowledged, i.e., the event is an "unacknowledged" event.

BrokerQueueBrowserException BrokerQueueBrowserException BrokerQueueBrowserException

384

webMethods Broker Administration Java API Programmers Guide Version 8.2

12 Java API Administration Reference

Possible Exceptions
BrokerQueueBrowserException

Meaning Invalid input arguments. Means that the array length of sequence number is not equal to the array length of events. No event was found on the queue for one or more of the specified receipt sequence numbers. The seqns or the events parameter is null or of array length zero. A duplicate sequence number is found on the array

BrokerInvalidSequenceNumberException

BrokerNullParameterException BrokerOutOfRangeException

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. Possible Exceptions
BrokerQueueBrowserException BrokerQueueBrowserException

Meaning The queue browser is invalid. A receipt sequence number of value zero is specified, which is not a valid receipt sequence number. The client queue is busy; retry the operation. No event was found on the queue for one or more of the specified receipt sequence numbers.

BrokerQueueBrowserException BrokerInvalidSequenceNumberException

webMethods Broker Administration Java API Programmers Guide Version 8.2

385

12 Java API Administration Reference

Possible Exceptions
BrokerNullParameterException BrokerOutOfRangeException

Meaning The seqns parameter is null or of array length zero. A duplicate sequence number is found on the array.

insertEventsAtHead
void insertEventsAtHead( BrokerEvent[] events) throws BrokerException

Inserts events into the client queue at the head position (queue position of zero). Possible Exceptions
BrokerQueueBrowserException BrokerInvalidEventException BrokerNoPermissionException

Meaning The queue browser is invalid. One or more of the specified event is invalid. The target client or remote Broker's forwarding queue does not have permission to subscribe to one or more of the specified events. The events parameter is null or of array length zero or one of the array element is null.

BrokerNullParameterException

insertEventsAtTail
void insertEventsAtTail( BrokerEvent[] events) throws BrokerException

Inserts events into the queue at the tail position (queue position "queue length minus one"). events Possible Exceptions
BrokerQueueBrowserException BrokerInvalidEventException BrokerNoPermissionException BrokerNullParameterException

An array of events that you want to insert into the queue. Meaning The queue browser is invalid. One or more of the specified event is invalid. The target client does not have permission to subscribe to one or more of the specified events. The events parameter is null or of array length zero or one of the array element is null.

386

webMethods Broker Administration Java API Programmers 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. seqns events An array of sequence numbers that identify the events to be modified in the queue An array of BrokerEvent that will be updated in place of the events in the queue. Meaning The queue browser is invalid. A receipt sequence number of value zero is specified, which is not a valid receipt sequence number. The queue is busy; retry the operation. The storage types of replaced and replacing events do not match. 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. No event was found on the client queue for one or more of the specified receipt sequence numbers. The seqns or the events parameter is null or of array length zero. A duplicate sequence number is found on the array.

Possible Exceptions
BrokerQueueBrowserException BrokerQueueBrowserException

BrokerQueueBrowserException BrokerQueueBrowserException BrokerQueueBrowserException

BrokerInvalidSequenceNumberException

BrokerNullParameterException BrokerOutOfRangeException

BrokerLogConfig
class BrokerLogConfig extends java.lang.Object

webMethods Broker Administration Java API Programmers 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: Level Alert Warning Informational Description Identifies critical messages. Identifies important messages. Identifies informational messages.

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

log_config

The object being copied.

Constructor that makes a new log configuration object that is a copy of log_config.

388

webMethods Broker Administration Java API Programmers Guide Version 8.2

12 Java API Administration Reference

Possible Exceptions
BrokerNullParameterException

Meaning The log_config parameter is null.

Methods
clearLogOutput
void clearLogOutput( String code) throws Brokerexception

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

Deletes one entry from the specified log output. Possible Exceptions
BrokerNullParameterException

Meaning The code parameter is null.

See Also: BrokerLogConfig.clearLogOutputs

clearLogOutputs
void clearLogOutputs()

Deletes all entries from all log outputs. See: BrokerLogConfig.clearLogOutput.

clearLogTopic
void clearLogTopic( String code) throws BrokerException

webMethods Broker Administration Java API Programmers Guide Version 8.2

389

12 Java API Administration Reference

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

Deletes one entry from a single log topic. Possible Exceptions

BrokerNullParameterException

Meaning The code parameter is null.

See Also: BrokerLogConfig.clearLogTopics

clearLogTopics
void clearLogTopics()

Deletes all entries from all log topics. See: BrokerLogConfig.clearLogTopic

getLogOutput
BrokerLogConfigEntry getLogOutput( String code) throws BrokerException

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

Returns the state of the specified log output. For more information, see BrokerLogConfigEntry. Possible Exceptions
BrokerNullParameterException BrokerOutOfRangeException

Meaning The code parameter is null. The code parameter is not in this log configuration.

390

webMethods Broker Administration Java API Programmers 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

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

Returns the state of the specified log topic. See BrokerLogConfigEntry on page 394 for more information. Possible Exceptions
BrokerNullParameterException BrokerOutOfRangeException

Meaning The code parameter is null. The code parameter is not set in this log configuration.

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

webMethods Broker Administration Java API Programmers Guide Version 8.2

391

12 Java API Administration Reference

setLogOutput
void setLogOutput( BrokerLogConfigEntry log_output) throws BrokerException

log_output

Specifies the type and state of log output that is to be set.

Sets the value of a single log topic to the specified state. See BrokerLogConfigEntry on page 394 for more information. Possible Exceptions
BrokerNullParameterException

Meaning log_output parameter or log_output.code is null.

See Also: BrokerLogConfig.getLogOutput, BrokerLogConfig.getLogOutputs, BrokerLogConfig.setLogOutput

setLogOutput
void setLogOutput( String code, boolean enabled, String value) throws BrokerException

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 value

If set to true, this output is enabled. The value to be set. Usually set to null.

Sets or creates a single log output state. See BrokerLogConfigEntry on page 394 for more information. Possible Exceptions
BrokerNullParameterException

Meaning The code parameter is null.

See Also: BrokerLogConfig.getLogOutput, BrokerLogConfig.getLogOutputs, BrokerLogConfig.setLogOutput

392

webMethods Broker Administration Java API Programmers Guide Version 8.2

12 Java API Administration Reference

setLogTopic
void setLogTopic( BrokerLogConfigEntry log_topic) throws BrokerException

log_topic

The log topic that is to be set.

Sets the value of a single log topic's state. See BrokerLogConfigEntry on page 394 for more information. Possible Exceptions
BrokerNullParameterException

Meaning log_topic parameter is null or log_topic.code is null.

See Also:
BrokerLogConfig.getLogTopic, BrokerLogConfig.getLogTopics, BrokerLogConfig.setLogTopic

and

setLogTopic
void setLogTopic( String code, boolean enabled, String value) throws BrokerException

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 value

If set to true, this topic is enabled. The value to be set. Usually set to null.

Sets the value of a single log output's state. See BrokerLogConfigEntry on page 394 for more information. Possible Exceptions
BrokerNullParameterException

Meaning The code parameter is null.

See Also: BrokerLogConfig.getLogTopic, BrokerLogConfig.getLogTopics, and BrokerLogConfig.setLogTopic

webMethods Broker Administration Java API Programmers 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)

indent_level

The number of 4-space indentations that should be generated in the output.

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.

394

webMethods Broker Administration Java API Programmers 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

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 new_value

If true, indicates this log output or topic is enabled. Otherwise, it is disabled. A string that is associated with the log output or topic. Usually set to null.

Creates an initialized log entry.

BrokerMonitorClient
public class BrokerMonitorClient extends java.lang.Object

This class represents a Broker Monitor client.

webMethods Broker Administration Java API Programmers Guide Version 8.2

395

12 Java API Administration Reference

Constant
BROKER_MONITOR_DEFAULT_PORT

Constructors
BrokerMonitorClient
BrokerMonitorClient(String broker_monitor_host) throws BrokerException

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.

Creates a BrokerMonitorClient object for the specified Broker Monitor host. Make sure the Broker Monitor process is running before creating the BrokerMonitorClient object. Possible Exceptions
BrokerCommFailureException BrokerHostNotFoundException BrokerNotRunningException BrokerNullParameterException

Meaning A problem occurred while establishing the connection. The specified Broker Monitor host cannot be located. A Broker Monitor could not be found on the broker_monitor_host. The broker_monitor_host parameter is null.

BrokerMonitorClient
BrokerMonitorClient( String broker_monitor_host, BrokerConnectionDescriptor desc) throws BrokerException

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. The connection descriptor to use for the new BrokerMonitorClient. If null, a default connection will be established.

desc

Creates a BrokerMonitorClient object for the specified Broker Monitor host. Make sure the Broker Monitor process is running before creating the BrokerMonitorClient object.

396

webMethods Broker Administration Java API Programmers Guide Version 8.2

12 Java API Administration Reference

Possible Exceptions
BrokerCommFailureException BrokerHostNotFoundException BrokerNotRunningException BrokerNullParameterException

Meaning A problem occurred while establishing the connection. The specified Broker Monitor host cannot be located. A Broker Monitor could not be found on the broker_monitor_host. The broker_monitor_host parameter is null.

Methods
destroy
void destroy() throws BrokerException

Destroys the Broker Monitor client. Marks the local Broker Monitor client object as disconnected and throws an exception. Possible Exception
BrokerInvalidClientException

Meaning The Broker Monitor client has been destroyed or disconnected.

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

base_port

The port number of the Broker Server to which this Broker Monitor client is connected.

webMethods Broker Administration Java API Programmers Guide Version 8.2

397

12 Java API Administration Reference

first_entry locale num_entries

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. The locale. If set to null, the Broker Server's default locale is used. The maximum number of log entries desired. If set to SERVER_LOG_ALL_ENTRIES, all entries in the log will be retrieved.

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. Possible Exceptions
BrokerIncompatibleVersionException BrokerInvalidClientException BrokerNoPermissionException BrokerOutOfRangeException

Meaning Broker Server version does not support this operation. TheBroker Monitor client has been destroyed or disconnected. The Broker Monitor client has limited access. The value of num_entries parameter is less than -1.

getServerLogStatus
BrokerServerLogInfo getServerLogStatus( int base_port) throws BrokerException

base_port

The port number of the Broker Server.

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. Possible Exceptions
BrokerIncompatibleVersionException BrokerInvalidClientException BrokerNoPermissionException

Meaning Broker Server version does not support this operation. The Broker Monitor client has been destroyed or disconnected. The Broker Monitor client has limited access.

398

webMethods Broker Administration Java API Programmers Guide Version 8.2

12 Java API Administration Reference

getServerRunStatus
int getServerRunStatus( int port) throws BrokerException

port

The port number of the Broker Server.

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 Possible Exceptions
BrokerInvalidClientException BrokerUnknownServerException

Meaning The Broker Monitor client has been destroyed or disconnected. No Broker Server is configured on the specified port.

getServers
BrokerServerInfo[] getServers() throws BrokerException

Returns the configuration details of all Broker Servers on the specified host. Possible Exception
BrokerInvalidClientException

Meaning TheBroker Monitor client has been destroyed or disconnected.

getVersion
String getVersion() throws BrokerException

Returns the version of Broker Monitor. Possible Exception

BrokerInvalidClientException

Meaning The Broker Monitor client has been destroyed or disconnected.

webMethods Broker Administration Java API Programmers 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

base_port older_than

The port number of the Broker Server. The date for deleting entries that are older than or equal to the older_than date.

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. Possible Exceptions
BrokerIncompatibleVersionException BrokerInvalidClientException BrokerNoPermissionException BrokerNullParameterException

Meaning Broker Server version does not support this operation. The Broker Monitor client has been destroyed or disconnected. The Broker Monitor client has limited access. The value of the older_than parameter is null.

reloadConfig
void reloadConfig() throws BrokerException

Broker Monitor reloads the configuration of all the connected Broker Servers.

reloadConfigForServer
void reloadConfigForServer( int port ) throws BrokerException

port

The port number of the Broker Server.

Broker Monitor reloads the configuration of the Broker Server running on port.

400

webMethods Broker Administration Java API Programmers Guide Version 8.2

12 Java API Administration Reference

Possible Exceptions
BrokerInvalidClientException BrokerUnknownServerException

Meaning The Broker Monitor client has been destroyed or disconnected. No Broker Server is configured on the specified port.

startServer
void startServer( int port ) throws BrokerException

port

The port number of the Broker Server.

Broker Monitor client starts the Broker Server configured on the specified port. Possible Exceptions
BrokerInvalidClientException BrokerUnknownServerException

Meaning The Broker Monitor client has been destroyed or disconnected. No Broker Server is 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

webMethods Broker Administration Java API Programmers 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)

new_name new_directory

The name of the Broker's executable file. The name of the directory where the Broker's output will be written.

Creates an initialized process information object.

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

402

webMethods Broker Administration Java API Programmers Guide Version 8.2

12 Java API Administration Reference

In addition to the listed exceptions, any communications exception can be thrown. Possible Exceptions
BrokerTimeoutException BrokerOutOfRangeException BrokerQueueBrowserException BrokerQueueBrowserException

Meaning The timeout is reached before an event arrives. The max_events or msecs parameter is less than zero. The queue browser is invalid. The event at the last cursor position was removed. Reset the cursor to a valid position before attempting a browse operation. The queue is busy; retry the operation later. 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. The client has been destroyed or is disconnected.

BrokerQueueBrowserException BrokerQueueBrowserException

BrokerInvalidClientException

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. Possible Exceptions
BrokerQueueBrowserException

Meaning The queue browser is invalid.

getFilters
COM.activesw.api.client.BrokerFilterDescriptor[] getFilters() throws BrokerException

Returns the list of filters currently set on the client queue browser. Possible Exceptions
BrokerQueueBrowserException

Meaning The queue browser is invalid.

webMethods Broker Administration Java API Programmers 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. Possible Exceptions
BrokerQueueBrowserException

Meaning The queue browser is invalid.

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. Possible Exceptions
BrokerQueueBrowserException BrokerFilterParseException BrokerInvalidFilterException BrokerNullParameterException BrokerUnknownEventTypeException

Meaning The queue browser is invalid. An error occurred while parsing the filter expression The specified filter expression on the filter object is invalid. The filter parameter is null or the filter expression on the BrokerFilterDescriptor is null. The specified event type on the filter object does not exist on Broker.

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
BrokerQueueBrowserException

Meaning The queue browser is invalid.

404

webMethods Broker Administration Java API Programmers Guide Version 8.2

12 Java API Administration Reference

Possible Exceptions
BrokerFilterParseException BrokerInvalidFilterException BrokerNullParameterException BrokerUnknownEventTypeException

Meaning An error occurred while parsing the filter expression The specified filter expression on the filter object is invalid. The filters parameter is null or the filter expression on the BrokerFilterDescriptor is null. The specified event type on the filter object does not exist on Broker.

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". Possible Exceptions
BrokerQueueBrowserException

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

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

webMethods Broker Administration Java API Programmers 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 Programmers 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

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.

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. Possible Exceptions
BrokerCommFailureException BrokerHostNotFoundException

Meaning A problem occurred establishing the connection. The specified host cannot be located.

webMethods Broker Administration Java API Programmers Guide Version 8.2

407

12 Java API Administration Reference

Possible Exceptions
BrokerNotRunningException BrokerNullParameterException

Meaning A Broker could not be found on the broker_host. The broker_host parameter is null.

Methods
createBroker
void createBroker( String broker_name, String description, boolean is_default) throws BrokerException

broker_name description is_default

The name of the Broker that is being created. A description of this Broker. If set to true, this will be the default Broker for this host.

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 Programmers Guide. Possible Exceptions
BrokerExistsException BrokerInvalidBrokerNameException BrokerInvalidClientException BrokerNoPermissionException BrokerNullParameterException

Meaning A Broker with the same broker_name already exists on the host. The broker_name is not valid. The BrokerServerClient has been destroyed or disconnected. Permission to create a Broker on the host was denied. broker_name or description parameter is null.

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.

408

webMethods Broker Administration Java API Programmers Guide Version 8.2

12 Java API Administration Reference

Possible Exceptions
BrokerInvalidClientException

Meaning The BrokerServerClient has been destroyed or disconnected.

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. Port number base port minus 1 base port minus 2 Possible Exceptions
BrokerInvalidClientException

Description Used for SSL connections without client authentication. Used for SSL connections with client authentication. Meaning The BrokerServerClient has been destroyed or disconnected.

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. Possible Exceptions
BrokerInvalidClientException BrokerNoPermissionException

Meaning The BrokerServerClient has been destroyed or disconnected. Client does not have permission to obtain the Broker's active port.

getActiveSSLConfig
BrokerSSLConfig getActiveSSLConfig() throws BrokerException

webMethods Broker Administration Java API Programmers 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. Possible Exceptions
BrokerInvalidClientException BrokerNoPermissionException

Meaning The BrokerServerClient has been destroyed or disconnected. The client does not have permission to obtain the Broker's active SSL configuration.

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. Possible Exceptions
BrokerInvalidClientException BrokerNoPermissionException BrokerIncompatibleVersionException

Meaning The BrokerServerClient has been destroyed or disconnected. The Client does not have permission to obtain the Broker's active SSL configuration. If the Broker does not support the old form of SSL configuration.

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

410

webMethods Broker Administration Java API Programmers Guide Version 8.2

12 Java API Administration Reference

Important! This method only works with Broker Servers 7.1 version and higher. Possible Exceptions
BrokerInvalidClientException BrokerNoPermissionException

Meaning The BrokerServerClient has been destroyed or disconnected. Client does not have permission to obtain the Broker's active SSL configuration.

getBasicAuthIdentity
public BrokerBasicAuthIdentity getBasicAuthIdentity() throws BrokerException

Returns the Broker Server's basic authentication identity that is in use. Possible Exception
BrokerInvalidClientException BrokerNoPermissionException BrokerIncompatibleVersionException

Meaning The BrokerServerClient has been destroyed or is disconnected. The client does not have permission to obtain the Broker's basic authentication identity. The Broker Server does not support this operation.

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 Exception
BrokerInvalidClientException BrokerIncompatibleVersionException

Meaning The BrokerServerClient has been destroyed or is disconnected. The Broker Server does not support this operation.

webMethods Broker Administration Java API Programmers 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. Possible Exceptions
BrokerInvalidClientException BrokerNoPermissionException

Meaning The BrokerServerClient has been destroyed or is disconnected. The client does not have permission to obtain the Broker's active SSL configuration.

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. Possible Exceptions
BrokerInvalidClientException BrokerNoPermissionException

Meaning The BrokerServerClient has been destroyed or disconnected. Client does not have permission to obtain the host's Access Control List.

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.

412

webMethods Broker Administration Java API Programmers Guide Version 8.2

12 Java API Administration Reference

Possible Exceptions
BrokerInvalidClientException

Meaning The BrokerServerClient has been destroyed or disconnected.

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. Possible Exceptions
BrokerInvalidClientException

Meaning The BrokerServerClient has been destroyed or disconnected.

See Also: BrokerServerClient.getBrokers and BrokerServerClient.setDefaultBrokerName

getDescription
String getDescription() throws BrokerException

Returns a string containing a description for the Broker Server. Possible Exceptions
BrokerInvalidClientException

Meaning The BrokerServerClient has been destroyed or disconnected.

See Also: BrokerServerClient.setDescription

getDNsFromCertFile
String[] getDNsFromCertFile( throws BrokerException String certificate_file, String password)

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 Programmers Guide Version 8.2

413

12 Java API Administration Reference

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.

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. Possible Exceptions
BrokerFileNotFoundException BrokerInvalidClientException BrokerNoPermissionException

Meaning The specified certificate_file could not be found. The BrokerServerClient has been destroyed or disconnected. The password is invalid, or certificate_file does not contain certificates, or the client does not have permission to access the SSL information.

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. Possible Exceptions
BrokerInvalidClientException BrokerIncompatibleVersionException BrokerNoPermissionException BrokerTimeoutException

Meaning The BrokerServerClient has been destroyed or disconnected. The Broker does not support FIPS. The client does not have permission to access the FIPS information. The FIPS information was not returned within the time-out interval.

414

webMethods Broker Administration Java API Programmers 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. Possible Exceptions
BrokerInvalidClientException BrokerNoPermissionException

Meaning The BrokerServerClient has been destroyed or disconnected. The client does not have permission to access the SSL information.

See Also: BrokerServerClient.setLicense

getLicenseContent
String getLicenseContent() throws BrokerException

Returns a string containing the Broker host's license file content. Possible Exceptions
BrokerInvalidClientException BrokerNoPermissionException

Meaning The BrokerServerClient has been destroyed or disconnected. The client does not have permission to access the SSL information.

See Also: BrokerServerClient.setLicenseContent

webMethods Broker Administration Java API Programmers 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. Possible Exceptions
BrokerInvalidClientException

Meaning The BrokerServerClient has been destroyed or disconnected.

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. Possible Exceptions
BrokerInvalidClientException

Meaning The BrokerServerClient has been destroyed or disconnected.

See Also: BrokerServerClient.pruneServerLog and BrokerServerClient.resumePublishProcessing.

getRootDNsFromCertFile
String[] String String throws getRootDNsFromCertFile( certificate_file, password) BrokerException

certificate_file password

The certificate file whose trusted root distinguished names are to be returned. The password for the certificate file. May be null if certificate_file is also null.

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.

416

webMethods Broker Administration Java API Programmers 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. Possible Exceptions
BrokerFileNotFoundException BrokerInvalidClientException BrokerNoPermissionException

Meaning The specified certificate_file could not be found or could not be read. The BrokerServerClient has been destroyed or disconnected. The password specified is not valid or certificate_file does not contain certificates.

getDNFromKeyStore
String getDNsFromKeystore( String keystore, String password, BrokerSSLConfigV2.KeystoreType keystoreType) throws BrokerException

keystore password keystoreType

The certificate file whose distinguished name is to be returned. The password for the keystore file. May be null if keystore is also null. The keystoreType parameter specifies the type of keystore: either PKCS12 or PEM.

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. Possible Exceptions
BrokerInvalidClientException BrokerNoPermissionException

Meaning The BrokerServerClient has been destroyed or disconnected. The client does not have permission to access the SSL information.

See Also: BrokerServerClient.getSSLStatus.

webMethods Broker Administration Java API Programmers 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. Possible Exceptions
BrokerFileNotFoundException BrokerInvalidClientException BrokerNoPermissionException BrokerNullParameterException BrokerSSLConfigException

Meaning If the keystore is not found or cannot be read. The client has been destroyed. If the password is invalid or if the file is not a keystore, or if the client has limited access. If keystore is null. If the keystoreType is invalid.

getRootDNsFromTrustStore
String getDNsFromKeystore( String truststore, throws BrokerException

truststore

The trusted root whose distinguished name is to be returned.

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. Possible Exceptions
BrokerInvalidClientException BrokerNoPermissionException

Meaning The BrokerServerClient has been destroyed or disconnected. The client does not have permission to access the SSL information.

See Also: BrokerServerClient.getSSLStatus.

getSavedSSLConfig
BrokerSSLConfig getSavedSSLConfig() throws BrokerException

418

webMethods Broker Administration Java API Programmers 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. Possible Exceptions
BrokerInvalidClientException BrokerNoPermissionException

Meaning The BrokerServerClient has been destroyed or disconnected. The client does not have permission to access the SSL information.

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. Possible Exceptions
BrokerInvalidClientException BrokerNoPermissionException BrokerIncompatibleVersionException

Meaning The BrokerServerClient has been destroyed or disconnected. The client does not have permission to access the SSL information. If the Broker does not support the old form of SSL configuration.

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.

webMethods Broker Administration Java API Programmers Guide Version 8.2

419

12 Java API Administration Reference

Important! This method only works with Broker Servers 7.1 version and higher. Possible Exceptions
BrokerInvalidClientException BrokerNoPermissionException BrokerIncompatibleVersionException

Meaning The BrokerServerClient has been destroyed or disconnected. The client does not have permission to access the SSL information. If the Broker does not support this call.

getServerLogEntries
BrokerServerLogEntry[] getServerLogEntries( BrokerDate first_entry, String locale, int num_entries) throws BrokerException

first_entry locale num_entries

The date of the first entry desired. If null, the entries will start with the first one that appears in the Server's log. The locale. If set to null, the server's default locale is used. The maximum number of log entries desired. If set to SERVER_LOG_ALL_ENTRIES, all entries in the log will be retrieved.

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
BrokerIncompatibleVersionException BrokerInvalidClientException BrokerNoPermissionException BrokerOutOfRangeException

Meaning The Broker Server does not support this operation. The BrokerServerClient has been destroyed or disconnected. The client does not have permission to access the SSL information. The n parameter is less than -1.

420

webMethods Broker Administration Java API Programmers 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. Possible Exceptions
BrokerIncompatibleVersionException BrokerInvalidClientException BrokerNoPermissionException

Meaning The Broker Server does not support this operation. The BrokerServerClient has been destroyed or disconnected. The client does not have permission to access the SSL information.

See Also: BrokerServerClient.getServerLogEntries and BrokerServerClient.pruneServerLog

getServerProcessRunStatus
static int getServerProcessRunStatus( String broker_host) throws BrokerException

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

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

webMethods Broker Administration Java API Programmers Guide Version 8.2

421

12 Java API Administration Reference

Possible Exceptions
BrokerHostNotFoundException BrokerInvalidClientException BrokerNotRunningException BrokerNullParameterException BrokerUnknownServerException

Meaning The specified broker_host does not exist. The BrokerServerClient has been destroyed or disconnected. A Broker could not be found on the broker_host. The broker_host parameter is null. The specified broker_host has a monitor process running, but no server is specified on the port number specified.

See Also: BrokerServerClient.startServerProcess and BrokerServerClient.stopProcess

getServerProcessRunStatus
static int getServerProcessRunStatus( String broker_monitor_host, int monitor_port, int broker_port) throws BrokerException

broker_monitor_host monitor_port broker_port

The name of the Broker Monitor host that manages the Broker Server whose state is to be returned. The port number of the Broker Monitor. If you omit the port number, the default port number will be used (6850). 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.

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
BrokerHostNotFoundException

Meaning The specified broker_host does not exist.

422

webMethods Broker Administration Java API Programmers Guide Version 8.2

12 Java API Administration Reference

Possible Exceptions
BrokerInvalidClientException BrokerNotRunningException BrokerNullParameterException BrokerUnknownServerException

Meaning The BrokerServerClient has been destroyed or disconnected. A Broker could not be found on the broker_host. The broker_host parameter is null. The specified broker_host has a monitor process running, but no server is specified on the port number specified.

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. Possible Exceptions
BrokerInvalidClientException

Meaning The BrokerServerClient has been destroyed or disconnected.

See Also: BrokerServerClient.getSavedSSLConfig, BrokerServerClient.getActiveSSLConfig, and BrokerServerClient.setSSLConfig.

getStats
BrokerEvent getStats() throws BrokerException

webMethods Broker Administration Java API Programmers 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
createTime highestNumConnections highestNumSSLConnections highestNumConnectionsTime highestNumSSLConnectionsTime

Type
BrokerDate int int BrokerDate BrokerDate

Description The time the server was first started. The highest number of non-SSL connections since the server was started. The highest number of SSL connections since the server was started. The time when highestNumConnections was last changed. The time when
highestNumSSLConnections

was last

changed.
isDiskSpaceLow isDiskSpaceVeryLow isLicenseExpiringSoon isLicenseExpired licensedConnections boolean boolean boolean boolean int

Set to true if there is less than 1 megabyte of free disk space. Set to true if there is less than 100 kilobytes of free disk space. Set to true if the server's license will expire within a week. Set to true if the server's license has expired. Total number of connections, SSL and non-SSL, allowed by the server's license. If -1, there is no limit. Date when the server's license will expire. If zero, it will never expire. Total number of SSL connections allowed by the server's license. If -1, there is no limit. The number of seconds until the server's license expires. If zero, it will never expire. Current time on the Broker host. The number of non-SSL connections to this server. The number of SSL connections to this server.

licenseExpirationTime licensedSSLConnections

BrokerDate int

licenseTimeRemaining

int

now numConnections numSSLConnections

BrokerDate int int

424

webMethods Broker Administration Java API Programmers Guide Version 8.2

12 Java API Administration Reference

Field Name
serverStartTime

Type
BrokerDate

Description The time the server was most recently started.

Possible Exceptions
BrokerInvalidClientException

Meaning The BrokerServerClient has been destroyed or disconnected.

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: Field Name
guaranteedDiskFree

Type
long

Description 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. The name of the guaranteed disk partition. On a Windows platform, this is usually C:. 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. The number of kilobytes of disk space currently allocated for guaranteed space. 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.

guaranteedDiskName

string

guaranteedDiskSize

long

guaranteedSpaceAllocated guaranteedSpaceMax

long long

webMethods Broker Administration Java API Programmers Guide Version 8.2

425

12 Java API Administration Reference

Field Name
guaranteedSpaceReserved

Type
long

Description 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. 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." The number of kilobytes of space Broker sets as a limit for memory usage. The total number of kilobytes of space allocated by Broker on the heap. Current time on the Broker host. 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. The number of free kilobytes of persistent disk store space. The name of the persistent disk partition. 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. The number of kilobytes of disk space currently allocated for persistent space. The fixed number of kilobytes of disk space reserved for persistent space. If zero, the storage will be resized as needed. The number of kilobytes of disk space being used for persistent space.

guaranteedSpaceUsed

long

maxMemorySize memoryUsed now percentageCPUUsed

long long BrokerDate double

persistentDiskFree persistentDiskName persistentDiskSize

long string long

persistentSpaceAllocated persistentSpaceMax

long long

persistentSpaceUsed

long

426

webMethods Broker Administration Java API Programmers Guide Version 8.2

12 Java API Administration Reference

Field Name
swapSpaceFree swapSpaceMax systemTimeUsed

Type
long long double

Description The number of kilobytes of free swap space. The total number of kilobytes of swap space. The number of seconds of CPU system time used by the Broker Server since it was started. The number of seconds of CPU user time used by the Broker since it was started.

userTimeUsed

double

Possible Exceptions
BrokerInvalidClientException

Meaning The BrokerServerClient has been destroyed or disconnected.

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

older_than

The date of the entries that are to be deleted from the log.

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. Possible Exceptions
BrokerIncompatibleVersionException

Meaning The Broker Server does not support this operation.

webMethods Broker Administration Java API Programmers Guide Version 8.2

427

12 Java API Administration Reference

Possible Exceptions
BrokerInvalidClientException BrokerNoPermissionException BrokerNullParameterException

Meaning The BrokerServerClient has been destroyed or disconnected. The client does not have permission to access the SSL information. The older_than parameter is null.

See Also: BrokerServerClient.getServerLogEntries and BrokerServerClient.getServerLogStatus

registerConnectionCallback
void registerConnectionCallback( BrokerServerConnectionCallback obj, Object client_data) throws BrokerException

obj

The object whose BrokerServerConnectionCallback.handleHostConnectionChange method will be invoked when this BrokerServerClient is disconnected or reconnected. Data that is to be passed to the BrokerServerConnectionCallback.handleHostConnectionChange callback method. This may be set to null.

client_data

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. Possible Exceptions
BrokerInvalidClientException

Meaning The BrokerServerClient has been destroyed or disconnected.

See Also: BrokerServerConnectionCallback.handleHostConnectionChange

resumePublishProcessing
void resumePublishProcessing() throws BrokerException {

This methods resumes event publishing on the Broker Server.

428

webMethods Broker Administration Java API Programmers 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. Possible Exceptions
BrokerInvalidClientException

Meaning The BrokerServerClient has been destroyed or disconnected.

See Also: BrokerServerClient.getPublicationProcessingState and BrokerServerClient.pruneServerLog.

setAdminACL
void setAdminACL( BrokerAccessControlList acl) throws BrokerException

acl

The access control list to set for this Broker Server.

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. Possible Exceptions
BrokerInvalidAccessListException BrokerInvalidClientException BrokerNoPermissionException BrokerNullParameterException

Meaning The acl variable does not contain a valid access control list. The BrokerServerClient has been destroyed or disconnected. The client does not have permission to set the host's Access Control List. The acl parameter is null.

See Also: BrokerServerClient.getAdminACL

setBasicAuthIdentity
public void setBasicAuthIdentity( BrokerBasicAuthIdentity new_identity) throws BrokerException

new_identity

The authentication identity that is to be set on Broker Server.

Sets the Broker Server's identity for basic authentication. To disable the basic authentication identity, set the basic authentication username to null.

webMethods Broker Administration Java API Programmers Guide Version 8.2

429

12 Java API Administration Reference

Possible Exceptions
BrokerBasicAuthFailureException BrokerNullParameterException BrokerIncompatibleVersionException

Meaning Basic authentication failed for the user. The new_identity parameter is null. Broker Server does not support this operation.

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

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.

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. Possible Exceptions
BrokerInvalidClientException BrokerNoPermissionException BrokerUnknownBrokerNameException

Meaning The BrokerServerClient has been destroyed or disconnected. The client does not have permission to set the default Broker. The specified broker_name does not exist.

setDescription
void setDescription( String description) throws BrokerException

description

The description to set for this Broker Server.

Sets the description for this Broker Server. Possible Exceptions

BrokerInvalidClientException

Meaning The BrokerServerClient has been destroyed or disconnected.

430

webMethods Broker Administration Java API Programmers Guide Version 8.2

12 Java API Administration Reference

Possible Exceptions
BrokerNoPermissionException BrokerNullParameterException

Meaning The client does not have permission to set the description. The description parameter is null.

See Also: BrokerServerClient.getDescription

setLicense
void setLicense( String license) throws BrokerException

license

The full path of the license file to be used. Note: Type the license string for Broker Servers earlier than 8.2 version.

Sets the license for the host to which this BrokerServerClient is currently connected. Possible Exceptions
BrokerInvalidClientException BrokerInvalidLicenseException BrokerNoPermissionException BrokerNullParameterException

Meaning The BrokerServerClient has been destroyed or disconnected. The license is invalid. The client does not have permission to set the license. The license parameter is null.

See Also: BrokerServerClient.getLicense

setLicenseContent
void setLicenseContent( String licenseFileContent) throws BrokerException

licenseFileContent

The unabridged contents of the license file to be used by webMethods Broker.

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.

webMethods Broker Administration Java API Programmers Guide Version 8.2

431

12 Java API Administration Reference

Possible Exceptions
BrokerInvalidClientException BrokerInvalidLicenseException BrokerNoPermissionException BrokerNullParameterException

Meaning The BrokerServerClient has been destroyed or disconnected. The license is invalid. The client does not have permission to set the license. The licenseFileContent parameter is null.

See Also: BrokerServerClient.getLicenseContent

setLicenseFile
void setLicenseContent( String licenseFile) throws BrokerException

licenseFile

The full path of the license file to be used by webMethods Broker.

Sets the license file for the host to which this BrokerServerClient is currently connected. This is supported by webMethods Broker 8.0 and above. Possible Exceptions
BrokerInvalidClientException BrokerInvalidLicenseException BrokerNoPermissionException BrokerNullParameterException

Meaning The BrokerServerClient has been destroyed or disconnected. The license is invalid. The client does not have permission to set the license. The licenseFile parameter is null.

See Also: BrokerServerClient.getLogConfig

setLogConfig
void setLogConfig( BrokerLogConfig log_config) throws BrokerException

log_config

The new logging configuration to set.

Sets the Broker Server's logging configuration.

432

webMethods Broker Administration Java API Programmers Guide Version 8.2

12 Java API Administration Reference

See BrokerLogConfig on page 387 for more information. Possible Exceptions

BrokerInvalidClientException BrokerInvalidLogConfigException BrokerNoPermissionException

Meaning The BrokerServerClient has been destroyed or disconnected. One or more log configuration entries are invalid. If throw, all valid entries are still set. The client does not have permission to access the log configuration.

See Also: BrokerServerClient.getLogConfig

setSSLConfig
void setSSLConfig( BrokerSSLConfig new_config) throws BrokerException

new_config

The SSL configuration to use the next time the Broker Server is started.

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

Meaning The certificate file specified by new_config cannot be found. The BrokerServerClient has been destroyed or disconnected.

webMethods Broker Administration Java API Programmers Guide Version 8.2

433

12 Java API Administration Reference

Possible Exceptions
BrokerNoPermissionException

Meaning The parameter new_config specifies an invalid password or an invalid certificate file, or the client does not have permission to set this configuration. The parameter new_config specifies a certificate file, but the distinguished name is null. Or new_config is null. The distinguished name specified by new_config does not exist in the certificate file.

BrokerNullParameterException

BrokerUnknownNameException

See Also: BrokerServerClient.getActiveSSLConfig, BrokerServerClient.getDNsFromCertFile, BrokerServerClient.getSavedSSLConfig, and BrokerServerClient.getSSLStatus

setSSLConfig
void setSSLConfig( String certificate_file, String password, String distinguished_name) throws BrokerException

certificate_file

The certificate file whose distinguished names are to be used. If SSL will be disabled the next time this Broker Server is started.
null,

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. The distinguished name to be used by the Broker when it authenticates itself to Broker clients.

distinguished_name

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.

434

webMethods Broker Administration Java API Programmers Guide Version 8.2

12 Java API Administration Reference

Possible Exceptions
BrokerFileNotFoundException BrokerInvalidClientException BrokerNoPermissionException

Meaning The specified certificate_file could not be found. The BrokerServerClient has been destroyed or disconnected. The password is invalid, or certificate_file does not contain certificates, or the client does not have permission to modify the SSL information. The distinguished_name parameter is null, but the certificate_file is not null.

BrokerNullParameterException

See Also: BrokerServerClient.getActiveSSLConfig, BrokerServerClient.getDNsFromCertFile, BrokerServerClient.getSavedSSLConfig, and BrokerServerClient.getSSLStatus

setSSLConfig
void setSSLConfig( BrokerSSLConfigV2 config) throws BrokerException

config

The SSL configuration to use the next time the Broker Server is started.

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
BrokerFileNotFoundException BrokerInvalidClientException BrokerNoPermissionException

Meaning The keystore file specified by config cannot be found. The BrokerServerClient has been destroyed or disconnected. The parameter config specifies an invalid password or an invalid certificate file, or the client does not have permission to set this configuration. The parameter config specifies a keystore file, but the distinguished name is null. Or config is null.

BrokerNullParameterException

webMethods Broker Administration Java API Programmers Guide Version 8.2

435

12 Java API Administration Reference

Possible Exceptions
BrokerUnknownNameException

Meaning The distinguished name specified by config does not exist in the keystore file.

startServerProcess
void startServerProcess( String broker_host) throws BrokerException

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.

Starts the Broker Server process on the specified host if it is not already started. Possible Exceptions
BrokerHostNotFoundException BrokerInvalidClientException BrokerNoPermissionException BrokerNotRunningException BrokerNullParameterException BrokerSecurityException

Meaning The specified broker_host does not exist. The BrokerServerClient has been destroyed or disconnected. The client does not have permission to start Broker host process. A Broker Server could not be found on the broker_host. The broker_host parameter is null. The client is now in limited access mode because its distinguished name was not found in the Broker host's Access Control List.

See Also: BrokerServerClient.getServerProcessRunStatus and BrokerServerClient.stopProcess

startServerProcess
void startServerProcess( String broker_monitor_host int monitor_port int broker_port) throws BrokerException

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.

436

webMethods Broker Administration Java API Programmers Guide Version 8.2

12 Java API Administration Reference

monitor_port broker_port

The port number of the Broker Monitor. If you omit the port number, the default port number will be used (6850). 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.

Starts the Broker Server process on the specified host if it is not already started. Possible Exceptions
BrokerHostNotFoundException BrokerInvalidClientException BrokerNoPermissionException BrokerNotRunningException BrokerNullParameterException BrokerSecurityException

Meaning The specified broker_host does not exist. The BrokerServerClient has been destroyed or disconnected. The client does not have permission to start Broker host process. A Broker Server could not be found on the broker_host. The broker_host parameter is null. The client is now in limited access mode because its distinguished name was not found in the Broker host's Access Control List.

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. Possible Exceptions
BrokerInvalidClientException BrokerNoPermissionException

Meaning The BrokerServerClient has been destroyed or disconnected. The client does not have permission to stop the Broker host process.

See Also: BrokerServerClient.getServerProcessRunStatus and BrokerServerClient.startServerProcess

webMethods Broker Administration Java API Programmers 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);

client connect_state client_data

The Broker Server client whose connection state has changed. The client's connection state. This will be set to one of the values shown in the table below. Any data that your callback method needs to perform its processing. This data is defined when you register your BrokerServerConnectionCallback object.

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: connect_state
CONNECT_STATE_DISCONNECTED CONNECT_STATE_CONNECTED

Meaning The BrokerServerClient has been disconnected. The BrokerServerClient connection has been reestablished, because automatic reconnect was enabled.

438

webMethods Broker Administration Java API Programmers Guide Version 8.2

12 Java API Administration Reference

connect_state
CONNECT_STATE_RECONNECTED

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

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.

webMethods Broker Administration Java API Programmers 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 Programmers 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 Programmers 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 Programmers Guide.

Constructors
BrokerSharedEventTypeInfo
BrokerSharedEventTypeInfo()

Creates an empty BrokerShareEventTypeInfo object.

442

webMethods Broker Administration Java API Programmers Guide Version 8.2

12 Java API Administration Reference

BrokerSharedEventTypeInfo
BrokerSharedEventTypeInfo( String event_type, boolean accept_pub, boolean accept_sub)

event_type accept_pub accept_sub

The name of the event type to be shared. If set to true, this territory accepts event that are publish or delivered from a remote territory. If set to true, this territory can forward subscriptions or deliver events to the remote territory.

Creates and initializes a BrokerShareEventTypeInfo object.

Methods
toString
String toString()

Returns a string containing the Broker shared event type information in a humanreadable 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_name

The name of the event type.

webMethods Broker Administration Java API Programmers Guide Version 8.2

443

12 Java API Administration Reference

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. 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. Meaning The event_type_name, refuse_events, or refuse_updates parameter is null.

refuse_updates

Possible Exceptions
BrokerNullParameterException

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

444

webMethods Broker Administration Java API Programmers 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)

new_distinguished_name new_issuer_distinguished _name new_status new_serial_number new_begin_date new_end_date

The distinguished name for the certificate. The distinguished name of the authority that issued the certificate. The certificate's status. The certificate's serial number. The date when the certificate becomes valid. The date when the certificate expires.

Creates a certificate object with the specified attributes.

webMethods Broker Administration Java API Programmers 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 Programmers Guide Version 8.2

12 Java API Administration Reference

BrokerSSLConfig
BrokerSSLConfig( String cert_file, String password, String dist_name, String issuer_dist_name)

cert_file password dist_name issuer_dist_name

The name of the certificate file to use. The certificate file's password. The distinguished name the Broker Server will use when authenticating itself with Broker clients. The distinguished name of the certificate authority that issued the Broker Server's certificate.

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 }

webMethods Broker Administration Java API Programmers 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)

crl

The full path to the SSL CRL file used by the SSL configuration on Broker Server.

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.

448

webMethods Broker Administration Java API Programmers Guide Version 8.2

12 Java API Administration Reference

setCRLType
void setCRLType( String crlType) 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.

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

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

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.

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)

newTruststore

The full path to the truststore file on the machine where the Broker Server is running.

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.

450

webMethods Broker Administration Java API Programmers Guide Version 8.2

12 Java API Administration Reference

setTruststoreType
void setTruststoreType(BrokerSSLConfigV2.TruststoreType newTruststoreType)

newTruststoreType

The BrokerSSLConfigV2.TruststoreType object to specify the type of the truststore file.

Sets the type of the truststore file to be used by the SSL configuration.

setTruststoreType
void setTruststoreType(String newTruststoreType) throws BrokerSSLConfigException

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.

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

webMethods Broker Administration Java API Programmers 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 Programmers 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)

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.

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.

webMethods Broker Administration Java API Programmers 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 Programmers 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 Programmers 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)

indent_level hide_gateway_broker hide_accessible_territories

The number of 4-character spaces to use for indentation. If set to true, the gateway Broker's host and name as well as the is_local information, will be omitted. If set to true, the accessible_territories and is_complete information will be omitted.

Returns a string containing the territory gateway information.

webMethods Broker Administration Java API Programmers 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 Programmers 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 Programmers 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)

indent_level

The number of 4-character spaces to use for indentation.

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. Key
TRACE_BROKER_ADDED TRACE_BROKER_REMOVED TRACE_CLIENT_CONNECT TRACE_CLIENT_CREATE TRACE_CLIENT_DESTROY TRACE_CLIENT_DISCONNECT TRACE_CLIENT_LOCK TRACE_CLIENT_UNLOCK

Event description A Broker is being added to a territory. A Broker is being removed from a territory. A Broker client is being connected. A Broker client is being created. A Broker client is being disconnected. A Broker client is being destroyed. A Broker client queue is being locked. A Broker client queue is being unlocked.

webMethods Broker Administration Java API Programmers Guide Version 8.2

457

12 Java API Administration Reference

Key
TRACE_EVENT_DROP

Event description 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. An event has been added to a Broker client's event queue by an administrative Broker Client. An event has been deleted from a Broker client's queue by an administrative Broker Client. An event has been inserted into a Broker client's queue. An event has been peeked from a Broker client's queue. An event has been published by a Broker client. A Broker client has retrieved an event from its event queue. All other trace events.

TRACE_EVENT_ENQUEUE TRACE_EVENT_DELETE TRACE_EVENT_INSERT TRACE_EVENT_PEEK TRACE_EVENT_PUBLISH TRACE_EVENT_RECEIVE TRACE_OTHER

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.

458

webMethods Broker Administration Java API Programmers 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 received the Broker event. or

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 Programmers 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 Programmers 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 Programmers 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 Programmers 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 Programmers Guide Version 8.2

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 Programmers Guide. BrokerDependencyException Your 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. BrokerExistsException You have attempted to create a Broker with a name that is already being used by another Broker on the same Broker Server. BrokerInClusterException You 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. BrokerIncompatibleVersionException You 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. BrokerInTerritoryException You 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. BrokerInvalidAccessListException The Access Control List you specified is not valid. BrokerInvalidBrokerNameException The Broker name you specified contains illegal characters. See the appendix in the webMethods Broker Client Java API Programmers Guide for details on naming rules. BrokerInvalidClientGroupNameException The client group name you specified contains illegal characters. See the appendix in the webMethods Broker Client Java API Programmers Guide for details on naming rules. BrokerInvalidLogConfigException The log configuration object you have specified is not valid. BrokerInvalidClusterNameException The cluster name you specified when creating a cluster is not valid. See the appendix in the webMethods Broker Client Java API Programmers Guide for details on naming rules.

webMethods Broker Administration Java API Programmers Guide Version 8.2

463

A API Exceptions

BrokerInvalidNameException The application name you specified when creating a Broker client is not valid. See the appendix in the webMethods Broker Client Java API Programmers Guide for details on naming rules. BrokerInvalidTerritoryNameException The application name you specified when creating a territory is not valid. See the appendix in the webMethods Broker Client Java API Programmers Guide for details on naming rules. BrokerNotInClusterException You 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. BrokerNotInTerritoryException You 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. BrokerUnknownBrokerNameException You 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. BrokerUnknownClusterException You 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. BrokerUnknownTerritoryException You 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 Programmers Guide Version 8.2