8-2-sp1 broker java admin programmers guide

Title Page

webMethods Broker Administration Java APIProgrammer’s Guide

Version 8.2

April 2011

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

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

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

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

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

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

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

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



Table of Contents

About this Guide . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29Document Conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29Documentation Installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30Online Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30

1. Managing Broker Event Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34Understanding the BrokerAdminTypeDef . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34Listing Event Type Definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35

Getting Multiple Event Type Definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36Getting Event Type Definitions by Scope . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36

Getting Event Type Statistics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37Creating and Modifying Event Type Definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37

Modifying Event Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38Creating or Modifying Multiple Event Type Definitions . . . . . . . . . . . . . . . . . . . . . . . . . 39

Destroying Event Type Definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39Destroying Multiple Event Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39

Event Type Infosets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40Setting Event Type Infosets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40Creating or Modifying Multiple Infosets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40

Destroying Infosets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40Destroying Multiple Infosets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41

2. Getting Started . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44Overview of the webMethods Broker Administration API . . . . . . . . . . . . . . . . . . . . . . . . . . 44

BrokerServerClient . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45BrokerAdminClient . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46Monitoring Brokers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46Managing Security Configurations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46Managing Territories . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46Managing Clusters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47Managing Configurations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47

Using the Administration API for Java . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47Compatibility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47Application Development with webMethods Broker . . . . . . . . . . . . . . . . . . . . . . . . . . . 47Application Deployment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48

webMethods Broker Java API Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48

3. Managing Brokers and Broker Servers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50

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

Understanding Broker Server Clients . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50Creating a BrokerServerClient . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50Destroying a BrokerServerClient . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51Connection Notification . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51

Defining a Callback Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51Registering the Callback Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51Un-Registering Callback Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52

Managing a Broker Server Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52Getting Broker Server Statistics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52Getting System Usage Statistics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53Getting and Setting the Default Broker . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53Getting and Setting Log Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54Getting the Port Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54Getting and Setting the License . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55Starting and Stopping the Host Process . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55Managing Security Configurations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55

Managing Brokers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55Using Change Locks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55Listing all Brokers on a Host . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56Creating and Destroying Brokers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57

4. Managing Broker Clients . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60Understanding BrokerAdminClients . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60

Creating a BrokerAdminClient . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60Destroying a BrokerAdminClient . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62Using Multiple BrokerAdminClients . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62Disconnecting a BrokerAdminClient . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63Reconnecting a BrokerAdminClient . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63

Using the newOrReconnectAdmin Method . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64Broker Administration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64

Destroying a Broker . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64Getting and Setting the Broker Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65Getting Broker Statistics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65

Broker Client Administration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66Obtaining Broker Client Identifiers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66Getting Broker Client Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67Creating Broker Clients . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68Reconnecting a Remote Broker . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68Disconnecting Broker Clients . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68Disconnecting by Session Identifier . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69Destroying Broker Clients . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70Client State Sharing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70Setting the Last-published Sequence Number . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70Clearing a Broker Client's Queue . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71

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

Broker Client Subscriptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71Listing Subscriptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71Testing the Existence of a Subscription . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71Creating Subscriptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71Destroying Subscriptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72

Getting Broker Client Statistics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72Getting Broker Client Infosets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73

5. Managing Client Groups . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76Listing Client Groups . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76Listing Client Identifiers by Group . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77Getting Client Group Statistics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77Creating and Destroying Client Groups . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78

Life Cycle . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78Storage Type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79Setting Client Group Descriptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79Destroying Client Groups . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79

BrokerClientGroupInfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80Controlling Event Publications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80Controlling Event Subscriptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81Controlling Group Access . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82

6. Managing Security Configurations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84Access Control Lists . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84

Getting and Setting Authenticator Names . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85Getting and Setting Names . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85Converting to a String . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86

Broker Server Security Configurations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86Retrieving and Setting Broker Server Security Configurations . . . . . . . . . . . . . . . . . . . 86Retrieving and Setting Broker Server ACLs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87

Client Group Security Configurations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87Obtaining Security Information for Client Sessions . . . . . . . . . . . . . . . . . . . . . . . . . . . 87

Territory Security Configurations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88Setting Territory Security . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88Territory ACLs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88

Territory Gateway Security Configurations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89Setting Territory Security . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89Territory Gateway ACLs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89

Cluster Security Configurations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89Setting Cluster Security . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89Cluster ACLs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90

Cluster Gateway Security Configurations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90Setting Cluster Security . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90


Cluster Gateway ACLs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91

7. Managing Broker Territories . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94Using Territories . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94

Creating a New Territory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94Adding a Broker to an Existing Territory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95Removing a Broker from a Territory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95Getting Territory Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95Listing Brokers in a Territory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 96Obtaining Territory Statistics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 96Maintaining a Connection Between Brokers in a Territory . . . . . . . . . . . . . . . . . . . . . . 96

Activating the Keep-Alive Feature between Territory Brokers . . . . . . . . . . . . . . . . 96Checking the Keep-Alive Settings for a Broker . . . . . . . . . . . . . . . . . . . . . . . . . . . 97

Setting Territory Security . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97Using Territory Gateways . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97

Creating and Destroying Gateways . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98Setting Shared Event Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99Listing Local Gateways . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99Listing All Gateways . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99Managing Event Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99Obtaining Gateway Statistics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100Maintaining a Connection Between Gateway Brokers . . . . . . . . . . . . . . . . . . . . . . . . . 100

Activating the Keep-Alive Feature between Gateway Brokers . . . . . . . . . . . . . . . 100Checking the Keep-Alive Settings for a Gateway Broker . . . . . . . . . . . . . . . . . . . 101

Pausing a Gateway Broker . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101Pausing Traffic in Both Directions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101Pausing Traffic to and from Multiple Territories . . . . . . . . . . . . . . . . . . . . . . . . . . . 101Unpausing a Gateway Broker . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102Checking the Current Pause Setting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102

Static Gateway Forwarding . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102Refusing Document Type Updates Across a Gateway . . . . . . . . . . . . . . . . . . . . . . . . . 102

Update Refusal Classes and Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103Synchronizing Updates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103

Setting Territory Gateway Security . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104

8. Managing Broker Clusters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 105Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 106Using Clusters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 106

Creating a New Cluster . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 106Adding a Broker to an Existing Cluster . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 106Removing a Broker from a Cluster . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107Getting Cluster Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107Listing Brokers in a Cluster . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107Obtaining Cluster Statistics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107


Maintaining a Connection Between Brokers in a Cluster . . . . . . . . . . . . . . . . . . . . . . . 108Activating the Keep-Alive Feature between Cluster Brokers . . . . . . . . . . . . . . . . . 108Checking the Keep-Alive Settings for a Broker . . . . . . . . . . . . . . . . . . . . . . . . . . . 108

Setting Cluster Security . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 108Using Cluster Gateways . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109

Creating and Destroying Cluster Gateways . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109Setting Shared Event Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109Setting Primary Gateway . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 110Listing Local Gateways . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 110Listing All Gateways . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 110Managing Event Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 110Obtaining Gateway Statistics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111Maintaining a Connection Between Gateway Brokers . . . . . . . . . . . . . . . . . . . . . . . . . 111

Activating the Keep-Alive Feature between Gateway Brokers . . . . . . . . . . . . . . . 111Checking the Keep-Alive Settings for a Cluster Gateway Broker . . . . . . . . . . . . . 112

Pausing a Gateway Broker . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112Pausing Traffic in Both Directions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112Pausing Traffic to and from Multiple Clusters . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113Unpausing a Cluster Gateway Broker . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113Checking the Current Pause Setting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113

Static Gateway Forwarding . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113Refusing Document Type Updates Across a Gateway . . . . . . . . . . . . . . . . . . . . . . . . 114

Update Refusal Classes and Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114Synchronizing Updates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114

Setting Cluster Gateway Security . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115

9. Managing Site Configurations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 118Collection Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 118Server Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 118Broker Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 119Client Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 120Client Group Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121Event Type Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122Territory Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122Territory Gateway Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123

10. Monitoring Broker Activity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 126Activity and Trace Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 126

Activity Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 126Client Changes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 127Client Group Changes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 127Event Type Changes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 128Territory Changes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 128


Trace Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 129Dropped Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 129Remotely Dropped Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 130Enqueued Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 130Remotely Enqueued Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131Published Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131Remotely Published Event . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132Received Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132Remotely Received Event . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 133Peek Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 133Insert Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 134Delete Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 134

Activity Traces . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 134Understanding the BrokerTraceEvent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 135Obtaining Activity Traces . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 135

Broker Logging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 135Understanding the BrokerLogConfig . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 136Understanding the BrokerLogEntry . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 137

Broker Server Logs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 137Obtaining Log Entries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 137Obtaining Log Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 138Deleting Log Entries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 138

11. Queue Browser . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 139Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 140Client Queue Browser . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 140Using Client Queue Browser . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 141Forwarding Queue Browser . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 142Using Forwarding Queue Browser . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 144BrokerAdminClient . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 145BrokerClient . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 145BrokerQueueBrowser and BrokerClientQueueBrowser . . . . . . . . . . . . . . . . . . . . . . . . . . . . 146BrokerLockedQueueBrowser and BrokerLockedClientQueueBrowser . . . . . . . . . . . . . . . . 147Creating and Closing Client Queue Browsers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 148

For a Client Queue Browser . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 148For an Administrative Queue Browser With No Lock . . . . . . . . . . . . . . . . . . . . . . . . . . 149For a Administrative Queue Browser With a Lock . . . . . . . . . . . . . . . . . . . . . . . . . . . . 150

Creating and Closing Forwarding Queue Browsers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 151For an Administrative Queue Browser With No Lock . . . . . . . . . . . . . . . . . . . . . . . . . . 152

Acquiring a Queue Lock . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 153Releasing a Queue Lock . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 153Queue Position . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 153Filters on a Queue Browser . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 154

Setting a Single Filter on Queue Browser . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 155Setting Multiple Filters on Queue Browser . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 155


Resetting Filters on Queue Browser . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 156Viewing Currently Set Filters on Queue Browser . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 157

Viewing Queue Content . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 158Viewing a Client's Own Queue Content . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 158Administratively Viewing Contents of an Unlocked Client Queue . . . . . . . . . . . . . . . . 159Administratively Viewing Contents of a Locked Client Queue . . . . . . . . . . . . . . . . . . . 161Administratively Viewing Contents of an Unlocked Forwarding Queue . . . . . . . . . . . . 162Administratively Viewing Contents of a Locked Forwarding Queue . . . . . . . . . . . . . . . 164Identifying "Unacknowledged" Documents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 165

Rearranging Queue Content . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 166Modifying Documents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 166Inserting Documents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 168Deleting Documents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 169Unblocking the Forwarding Queue in a Territory or Cluster . . . . . . . . . . . . . . . . . . . . . 170Unblocking the Forwarding Queue in a Territory Gateway or Cluster Gateway . . . . . . 171

12. Java API Administration Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 173AccessControlList . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 175

Constructors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 175BrokerAccessControlList . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 175BrokerAccessControlList . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 175

Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 175getAuthNames . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 175getAuthNameState . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 175getUserNames . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 176getUserNameState . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 176setAuthNames . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 176setAuthNameState . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 177setAuthNameStates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 177setUserNames . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 178setUserNameState . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 178setUserNameStates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 179toString . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 179toString . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 180

BrokerAdminClient . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 180Constants . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 180Constructor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 180

BrokerAdminClient . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 180Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 182

abort Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 182abortForced . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 182abortForced . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 183

acquire Method . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 183acquireChangeLock . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 183

add Method . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 184


addBrokerToCluster . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 184check Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 185

checkAndRestartForwarding . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 185checkAndRestartForwarding . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 185

clear Method . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 186clearClientQueueById . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 186

commit Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 186commitForced . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 186commitForced . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 187

create Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 187createClient . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 187createClientGroup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 188createClientQueueBrowser . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 189createClientSubscriptionById . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 190createClientSubscriptionsById . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 191createCluster . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 192createClusterGateway . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 193createForwardQueueBrowser . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 194createLockedClientQueueBrowser . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 195createLockedForwardQueueBrowser . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 195createTerritory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 196createTerritoryGateway . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 197

delete Method . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 198deleteLogEvents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 198

destroy Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 198destroyBroker . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 198destroyClientById . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 199destroyClientGroup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 199destroyClientSubscriptionById . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 200destroyClientSubscriptionsById . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 201destroyClusterGateway . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 202destroyEventType . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 203destroyEventTypeInfoset . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 204destroyEventTypeInfosets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 204destroyEventTypes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 205destroyTerritoryGateway . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 206

disconnect Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 207disconnectClientById . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 207disconnectClientSessionById . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 208

does Method . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 208doesClientSubscriptionExistById . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 208

forget Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 209forgetForced . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 209forgetForced . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 210forgetForced . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 210


get Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 210getActivityTraces . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 210getAllClusterGateways . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 211getAllQueueStats . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 211getAllTerritoryGateways . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 213getBrokerDescription . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 213getBrokersInCluster . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 214getBrokersInTerritory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 214getBrokerStats . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 215getClientGroupACL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 217getClientGroupCanPublishList . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 217getClientGroupCanSubscribeList . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 218getClientGroupInfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 218getClientGroupInfos . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 219getClientGroupLogAcknowledgeList . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 219getClientGroupLogPublishList . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 220getClientGroupNames . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 220getClientGroupStats . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 221getClientGroupsWhichCanPublish . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 221getClientGroupsWhichCanSubscribe . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 222getClientIds . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 223getClientIdsByClientGroup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 223getClientIdsWhichAreSubscribed . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 224getClientInfoById . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 224getClientInfosById . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 225getClientInfosetById . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 225getClientQueueBrowsers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 226getClientQueueLock . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 226getClientStatsById . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 227getClientSubscriptionsById . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 228getClusterACL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 229getClusterGatewayACL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 229getClusterGatewayKeepAlive . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 230getClusterGatewayRefuseAllUpdates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 231getClusterGatewaySharedEventTypes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 231getClusterGatewayStats . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 232getClusterInfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 235getClusterStaticGatewayForwarding . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 235getClusterStats . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 236getEventAdminTypeDef . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 239getEventAdminTypeDefs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 239getEventAdminTypeDefsByScope . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 240getEventLogging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 241getEventTypeStats . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 241getHeuristicTransactions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 242


getLocalClusterGateways . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 243getLocalTerritoryGateways . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 244getLogEvents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 244getLogLength . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 245getPostPrepareTimeout . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 245getPostPrepareTimeoutAction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 245getPrePrepareTimeout . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 246getRecoverMode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 246getRemoteBrokerKeepAlive . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 246getStaticGatewayForwarding . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 247getTerritoryACL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 247getTerritoryGatewayACL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 248getTerritoryGatewayKeepAlive . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 248getTerritoryGatewayRefuseAllUpdates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 249getTerritoryGatewayRefuseEventTypeUpdates . . . . . . . . . . . . . . . . . . . . . . . 250getTerritoryGatewaySharedEventTypes . . . . . . . . . . . . . . . . . . . . . . . . . . . . 250getTerritoryGatewayStats . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 251getTerritoryInfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 254getTerritoryStats . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 255getTransactions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 258getTransactionsByClient . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 259

join method . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 260joinTerritory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 260

leave Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 261leaveCluster . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 261leaveTerritory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 262

new Method . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 263newOrReconnectAdmin . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 263

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

release Method . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 266releaseChangeLock . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 266

remove Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 266removeBrokerFromCluster . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 266removeBrokerFromTerritory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 267

set Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 268setBrokerDescription . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 268setClientGroupAccessLabelRequired . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 269setClientGroupACL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 270setClientGroupCanPublishList . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 270setClientGroupCanSubscribeList . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 271setClientGroupDescription . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 272setClientGroupLogAcknowledgeList . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 273setClientGroupLogPublishList . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 273setClientGroupRequiredEncryption . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 274


setClientInfosetById . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 274setClientLastPublishSequenceNumberById . . . . . . . . . . . . . . . . . . . . . . . . . . 275setClientStateShareLimitById . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 276setClusterACL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 277setClusterGatewayACL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 278setClusterGatewayKeepAlive . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 279setClusterGatewayPause . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 280setClusterGatewayRefuseAllUpdates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 281setClusterGatewaySecurity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 281setClusterGatewaySharedEventTypes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 282setClusterPrimaryGateway . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 284setClusterSecurity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 284setClusterStaticGatewayForwarding . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 285setEventAdminTypeDef . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 286setEventAdminTypeDefs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 286setEventLogging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 287setEventTypeInfoset . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 287setEventTypeInfosets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 288setEventTypesAndClientGroups . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 289setPostPrepareTimeout . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 291setPostPrepareTimeoutAction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 291setPrePrepareTimeout . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 292setRecoverMode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 292setRemoteBrokerKeepAlive . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 293setStaticGatewayForwarding . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 294setTerritoryACL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 294setTerritoryGatewayACL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 295setTerritoryGatewayKeepAlive . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 296setTerritoryGatewayPause . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 297setTerritoryGatewayRefuseAllUpdates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 298setTerritoryGatewayRefuseEventTypeUpdates . . . . . . . . . . . . . . . . . . . . . . . 298setTerritoryGatewaySecurity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 299setTerritoryGatewaySharedEventTypes . . . . . . . . . . . . . . . . . . . . . . . . . . . . 300setTerritorySecurity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 301

BrokerAdminTypeDef . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 302Constructors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 303

BrokerAdminTypeDef . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 303BrokerAdminTypeDef . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 303BrokerAdminTypeDef . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 304BrokerAdminTypeDef . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 304

Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 305clearField . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 305clearFields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 305clearModificationFlag . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 305getBaseTypeName . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 305


getDescription . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 306getFieldDef . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 306getFieldNames . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 306getFieldType . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 307getScopeTypeName . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 307getStorageType . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 308getTimeToLive . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 308getTypeName . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 308hasBeenModified . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 308insertFieldDef . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 309isSystemDefined . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 309orderFields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 310renameField . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 310setDescription . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 311setFieldDef . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 312setFieldType . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 312setModificationFlag . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 313setStorageType . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 313setTimeToLive . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 313setTypeName . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 314toString . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 314toString . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 315

BrokerAuthInfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 315Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 315

username . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 315authenticator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 315

Constructors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 315BrokerAuthInfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 315BrokerAuthInfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 316BrokerAuthInfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 316

Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 316getAuthenticator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 316getUserName . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 316setAuthenticator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 316setUserName . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 316toString . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 317toString . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 317

BrokerChangeLockInfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 317Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 317

acquired . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 317client_id . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 317session_id . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 317lock_time . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 318

BrokerClientGroupInfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 318Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 318


access_label_required . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 318description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 318is_system_defined . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 318life_cycle . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 318name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 318required_encryption . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 318storage_type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 319

Constructors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 319BrokerClientGroupInfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 319BrokerClientGroupInfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 319

Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 320toString . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 320toString . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 320

BrokerClientInfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 320Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 320

access_label . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 320app_name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 320authenticator_name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 320can_share_state . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 320client_group . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 321client_id . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 321high_pub_seqn . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 321sessions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 321shared_event_ordering . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 321state_share_limit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 321user_name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 321

Constructors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 322BrokerClientInfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 322BrokerClientInfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 322

Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 322toCompleteString . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 322toString . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 322toString . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 323

BrokerClientQueueBrowser . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 323Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 323

browseEvents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 323closeQueueBrowser . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 324getBrowserInfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 324getFilters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 324resetFilters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 325setFilter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 325setFilters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 325setPosition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 326

BrokerClientQueueBrowserInfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 326Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 326


clientId . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 326browserId . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 326browserSessionId . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 327locked . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 327createTime . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 327

Constructors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 327BrokerClientQueueBrowserInfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 327BrokerClientQueueBrowserInfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 327

BrokerClientSession . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 327Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 328

auth_info . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 328auth_protocol . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 328auth_version . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 328connect_time . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 328connection_id . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 328create_time . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 328encrypt_level . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 328encrypt_protocol . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 328encrypt_version . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 329ip_address . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 329last_activity_time . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 329platform_info . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 329port . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 329session_id . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 329ssl_certificate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 329

Constructors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 329BrokerClientSession . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 329BrokerClientSession . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 330

Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 330toString . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 330

BrokerClusterGatewayInfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 331Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 331

accessible_clusters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 331auth_type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 331encrypt_level . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 331gateway_broker_name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 331gateway_host_name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 331is_complete . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 331is_local . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 332is_primary_gateway . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 332remote_broker_description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 332remote_broker_name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 332remote_cluster_name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 332remote_host_name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 332

Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 332


toString . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 332toString . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 333

BrokerClusterInfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 333Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 333

auth_type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 333cluster_name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 333encrypt_level . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 333isLocalPublish . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 333

Constructor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 334BrokerClusterInfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 334BrokerClusterInfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 334


BrokerCompleteBroker . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 334Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 334

broker_name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 334brokers_in_territory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 335client_groups . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 335clients . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 335description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 335event_types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 335is_default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 335territory_name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 335

Constructors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 335BrokerCompleteBroker . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 335BrokerCompleteBroker . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 336

Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 336deepRefresh . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 336deepRetrieve . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 336deepStore . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 337refresh . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 338retrieve . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 338store . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 339toString . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 339toString . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 340write . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 340

BrokerCompleteClient . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 340Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 341

client_info . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 341infoset . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 341replace_subscriptions_on_store . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 341subscriptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 341

Constructors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 341BrokerCompleteClient . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 341


BrokerCompleteClient . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 341Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 342

refresh . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 342retrieve . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 342store . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 343toString . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 344toString . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 344write . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 345

BrokerCompleteClientGroup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 345Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 345

acl . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 345can_publish . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 346can_subscribe . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 346client_group_info . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 346ignore_change_errors_on_store . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 346replace_lists_on_store . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 346

Constructors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 346BrokerCompleteClientGroup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 346BrokerCompleteClientGroup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 346

Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 347refresh . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 347retrieve . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 347store . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 348toString . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 349toString . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 349write . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 349

BrokerCompleteCollection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 350Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 350

acls . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 350brokers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 350client_groups . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 350clients . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 350event_types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 351servers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 351

Constructors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 351BrokerCompleteCollection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 351

Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 351read . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 351readFile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 352toString . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 352toString . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 352write . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 353writeVersionNumber . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 353

BrokerCompleteEventType . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 354Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 354


infosets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 354replace_infosets_on_store . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 354type_def . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 354

Constructors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 355BrokerCompleteEventType . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 355BrokerCompleteEventType . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 355

Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 355refresh . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 355retrieve . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 356store . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 356toString . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 357toString . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 357write . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 358

BrokerCompleteServer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 358Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 358

acl . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 358brokers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 358description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 358host_name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 359license_key . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 359log_config . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 359port . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 359ssl_config . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 359

Constructors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 359BrokerCompleteServer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 359

Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 359deepRefresh . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 359deepRetrieve . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 360deepStore . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 361refresh . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 363retrieve . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 363store . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 364toString . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 365toString . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 365write . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 365

BrokerCompleteTerritory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 366Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 366

acl . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 366info . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 366other_brokers_in_territory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 366

Constructors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 366BrokerCompleteTerritory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 366BrokerCompleteTerritory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 366

Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 367refresh . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 367


retrieve . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 367store . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 368toString . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 368toString . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 368write . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 369

BrokerCompleteTerritoryGateway . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 369Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 370

acl . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 370info . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 370remote_can_publish . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 370

Constructors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 370BrokerCompleteTerritoryGateway . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 370BrokerCompleteTerritory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 370

Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 371refresh . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 371retrieve . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 371store . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 372toString . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 373toString . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 373write . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 374

BrokerFilterDescriptor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 374Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 374

eventTypeName . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 374filterExpr . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 374

Constructors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 375BrokerFilterDescriptor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 375BrokerFilterDescriptor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 375


BrokerForwardQueueBrowser . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 375Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 375

browseEvents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 375closeQueueBrowser . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 376getBrowserInfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 376getFilters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 376resetFilters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 377setFilter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 377setFilters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 377setPosition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 378

BrokerInfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 378Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 378

broker_host . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 378broker_name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 378cluster_name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 378description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 379


territory_name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 379Constructors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 379

BrokerInfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 379BrokerInfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 379

BrokerJoinFailureInfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 379Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 380

client_group_names . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 380event_type_names . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 380

Constructors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 380BrokerLockedClientQueueBrowser . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 380

Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 380deleteEvents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 380insertEventsAtHead . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 381insertEventsAtTail . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 381modifyEvents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 382

BrokerLockedForwardQueueBrowser . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 383Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 383

deleteEvents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 383insertEventsAtTail . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 384modifyEvents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 384

BrokerLockedQueueBrowser . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 385Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 385

deleteEvents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 385insertEventsAtHead . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 386insertEventsAtTail . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 386modifyEvents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 387

BrokerLogConfig . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 387Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 388Constructors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 388

BrokerLogConfig . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 388BrokerLogConfig . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 388

Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 389clearLogOutput . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 389clearLogOutputs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 389clearLogTopic . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 389clearLogTopics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 390getLogOutput . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 390getLogOutputs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 391getLogTopic . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 391getLogTopics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 391setLogOutput . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 392setLogOutput . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 392setLogTopic . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 393setLogTopic . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 393toString . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 394


toString . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 394BrokerLogConfigEntry . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 394

Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 394code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 394enabled . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 394value . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 395

Constructors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 395BrokerLogConfigEntry . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 395BrokerLogConfigEntry . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 395

BrokerMonitorClient . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 395Constant . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 396Constructors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 396

BrokerMonitorClient . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 396BrokerMonitorClient . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 396

Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 397destroy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 397getHostName . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 397getPort . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 397getServerLogEntries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 397getServerLogStatus . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 398getServerRunStatus . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 399getServers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 399getVersion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 399getVersionNumber . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 400pruneMonitorLog . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 400reloadConfig . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 400reloadConfigForServer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 400startServer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 401toString . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 401

BrokerProcessInfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 401Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 401

data_directory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 401exectuable_name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 401

Constructors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 402BrokerProcessInfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 402BrokerProcessInfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 402

BrokerQueueBrowser . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 402Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 402

browseEvents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 402closeQueueBrowser . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 403getBrowserInfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 403getFilters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 403resetFilters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 404setFilter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 404setFilters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 404


setPosition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 405BrokerQueueBrowserInfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 405

Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 405clientId . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 405browserId . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 405browserSessionId . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 406locked . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 406createTime . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 406

Constructors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 406BrokerQueueBrowserInfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 406BrokerQueueBrowserInfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 406

BrokerServerClient . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 406Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 407Constructors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 407

BrokerServerClient . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 407Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 408

createBroker . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 408destroy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 408getActivePort . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 409getActiveProcessInfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 409getActiveSSLConfig . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 409getActiveSSLConfigV2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 410getActiveSSLIdentity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 410getBasicAuthIdentity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 411getBasicAuthStatus . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 411getSavedSSLidentity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 412getAdminACL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 412getBrokers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 412getDefaultBrokerName . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 413getDescription . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 413getDNsFromCertFile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 413getFIPSMode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 414getHostName . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 415getLicense . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 415getLicenseContent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 415getLogConfig . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 416getPublicationProcessingState . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 416getRootDNsFromCertFile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 416getDNFromKeyStore . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 417getIssuerDNFromKeystore . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 418getRootDNsFromTrustStore . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 418getSavedSSLConfig . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 418getSavedSSLConfigV2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 419getSavedSSLIdentity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 419getServerLogEntries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 420


getServerLogStatus . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 421getServerProcessRunStatus . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 421getServerProcessRunStatus . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 422getServerVersionNumber . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 423getSSLStatus . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 423getStats . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 423getUsageStats . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 425getVersion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 427pruneServerLog . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 427registerConnectionCallback . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 428resumePublishProcessing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 428setAdminACL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 429setBasicAuthIdentity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 429setDefaultBrokerName . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 430setDescription . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 430setLicense . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 431setLicenseContent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 431setLicenseFile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 432setLogConfig . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 432setSSLConfig . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 433setSSLConfig . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 434setSSLConfig . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 435startServerProcess . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 436startServerProcess . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 436stopProcess . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 437toString . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 438

BrokerServerConnectionCallback . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 438Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 438

handleHostConnectionChange . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 438BrokerServerLogEntry . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 439

Constants . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 439Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 439

entry_msg_id . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 439entry_msg_text . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 439entry_type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 439time_stamp . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 440


BrokerServerLogInfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 440Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 440

first_entry . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 440last_entry . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 440num_entries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 440

BrokerSetFailureInfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 440Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 441


client_group_names_to_destroy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 441client_group_names_to_modify . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 441event_type_names_to_destroy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 441event_type_names_to_modify . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 441failure_type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 441

Constructor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 441BrokerSetFailureInfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 441

BrokerSharedEventTypeInfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 441Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 442

accept_publish . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 442accept_subscribe . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 442event_type_name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 442is_synchronized . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 442subscribe_filter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 442

Constructors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 442BrokerSharedEventTypeInfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 442BrokerSharedEventTypeInfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 443


BrokerSharedEventTypeRefuseUpdateInfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 443Constructor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 443

BrokerSharedEventTypeRefuseUpdateInfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 443BrokerSSLCertificate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 444

Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 444begin_date . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 444distinguished_name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 444end_date . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 444issuer_distinguished_name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 445serial_number . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 445status . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 445

Constructors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 445BrokerSSLCertificate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 445BrokerSSLCertificate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 445

BrokerSSLConfig . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 446Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 446

certificate_file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 446distinguished_name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 446issuer_distinguished_name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 446password . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 446

Constructors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 446BrokerSSLConfig . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 446BrokerSSLConfig . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 447

BrokerSSLConfigV2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 447Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 447

CRLType . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 447


KeystoreType . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 447TruststoreType . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 447SSLProtocol . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 447

Constructors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 448BrokerSSLConfigV2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 448BrokerSSLConfigV2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 448

Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 448getCipherSuites . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 448setCipherSuites . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 448getCRL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 448setCRL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 448getCRLType . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 448setCRLType . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 449getKeystore . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 449setKeystore . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 449getKeystorePassword . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 449setKeystorePassword . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 449getKeystoreType . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 449setKeystoreType . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 449getSslProtocol . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 450setSslProtocol . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 450getTruststore . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 450setTruststore . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 450getTruststoreType . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 450setTruststoreType . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 451setTruststoreType . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 451getVerifyDepth . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 451setVerifyDepth . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 451toString . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 451

BrokerSSLIdentity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 451Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 452

getDN . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 452getIssuerDN . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 452

BrokerSSLStatus . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 452Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 452

error_string . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 452level . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 452status . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 452

Constructors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 453BrokerSSLStatus . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 453BrokerSSLStatus . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 453

BrokerTerritoryGatewayInfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 453Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 454

accessible_territories . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 454auth_type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 454


encrypt_level . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 454gateway_broker_name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 454gateway_host_name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 454is_complete . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 454is_local . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 454is_primary_gateway . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 454remote_broker_description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 455remote_broker_name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 455remote_host_name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 455remote_territory_name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 455


BrokerTerritoryInfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 456Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 456

auth_type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 456encrypt_level . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 456isLocalPublish . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 456territory_name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 456

Constructor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 456BrokerTerritoryInfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 456


BrokerTraceEvent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 457Constants . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 457Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 458

app_name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 458broker_host . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 458broker_name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 458client_group . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 459client_id . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 459dest_client_id . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 459encrypt_level . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 459event_id . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 459event_type_name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 460has_tag . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 460ip_address . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 460is_authenticated . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 460key . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 460other_string . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 460recv_client_id . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 460seqn . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 461session_count . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 461session_id . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 461


tag . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 461track_id . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 461

Constructor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 461BrokerTraceEvent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 461


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


About this Guide

The webMethods Broker Administration Java API Programmer’s Guide describes the application programming interfaces (API) that you use to create event-based applications, using the Java language, which perform administrative functions.

This document is intended for use by programmers who are developing event--based applications using webMethods Broker. The reader is assumed to possess general knowledge of programming concepts and specific knowledge of the Java programming language. In addition, you should be familiar with the webMethods Broker systems concepts, administration, and the webMethods Broker APIs.

This book assumes you are familiar with the terminology and basic operations of your operating system. If you are not, see the applicable documentation for that operating system.

Document Conventions

Convention Description

Bold Identifies elements on a screen.

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

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

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

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

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

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

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

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


About this Guide

Documentation Installation

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

Online Information

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

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

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

6.x The installation directory of each product.

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

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

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

Access the latest version of product documentation.

Software AG Documentation Web site

http://documentation.softwareag.com


http://documentation.softwareag.com

About this Guide

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

See the Knowledge Center to:

Read technical articles and papers.

Download fixes and service packs.

Learn about critical alerts.

See the Products area to:

Download products.

Download certified samples.

Get information about product availability.

Access older versions of product documentation.

Submit feature/enhancement requests.

Empower Product Support Web site

https://empower.softwareag.com

Access additional articles, demos, and tutorials.

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

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

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

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

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

Software AG Developer Community for webMethods

http://communities.softwareag.com/

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


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

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

https://empower.softwareag.com

http://communities.softwareag.com/

About this Guide


1 Managing Broker Event Types

Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34

Understanding the BrokerAdminTypeDef . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34

Listing Event Type Definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35

Getting Event Type Statistics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37

Creating and Modifying Event Type Definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37

Destroying Event Type Definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39

Event Type Infosets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40

Destroying Infosets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40



Overview

This chapter describes how you can use the BrokerAdminClient interface, introduced in “Managing Broker Clients” on page 59, to obtain information about event types defined for a Broker. Reading this chapter should help you understand:

Listing event types defined for a particular Broker.

Listing all Broker clients which have subscriptions for an event type.

Obtaining event type statistics.

Creating or destroying an event type definition or event type infoset.

Getting or setting a event type's properties, including event fields and their types.

Note: For more information on event types and their features, see the webMethods Broker Client Java API Programmer’s Guide.

Understanding the BrokerAdminTypeDef

Many of the BrokerAdminClient methods described in this chapter use BrokerAdminTypeDef objects as a parameter or a returned value. The BrokerTypeDef class, described in the webMethods Broker Client Java API Programmer’s Guide, provides your client application with a read-only description of an event type definition. In contrast, the BrokerAdminTypeDef class allows your client application to both query and modify the properties of an event type definition.

Note: Unlike BrokerTypeDef objects, BrokerAdminTypeDef objects are not cached and are not affected if the client application's type definition cache is flushed.

BrokerAdminTypeDef objects are also used to represent the fields within an event definition. The following table shows the methods offered by the BrokerAdminTypeDef class.

Method Description

clearField

clearFields

Clears one or all fields in the type definition.

renameField Renames a field within a BrokerAdminTypeDef object.

clearModificationFlag

hasBeenModified

setModificationFlag

Manages the modification flag, which is used to track changes made to the event type definition.

getBaseTypeName Returns the event type name, without any event scope qualifier.

getScopeTypeName Returns the event type's scope name.



Listing Event Type Definitions

The BrokerClient.getEventTypeNames method, described in the webMethods Broker Client Java API Programmer’s Guide, can be used to return all the event type names defined for a Broker. Once you know the name of an event, you can use the BrokerAdminClient.getEventAdminTypeDef method to obtain an event type's definition. Your client must have permission to obtain this information.

The following example illustrates how to get an event type definition:

. . . String event_names[]; BrokerAdminTypeDef def; BrokerAdminClient c; try {

/* Create a Broker admin client */ c = new BrokerAdminClient(broker_host, broker_name, null,

getTypeName Returns the event type's fully-qualified name.

setTypeName Sets the fully-qualified name for the event type.

getDescription

setDescription

Manages the description for the event type.

getFieldDef

setFieldDef

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

getFieldNames Returns the names of the fields within an event or structure field.

getFieldType

setFieldType

Manages the data type of an event field's value.

getStorageType

setStorageType

Manages the event's storage type property.

getTimeToLive

setTimeToLive

Manages the event's time-to-live property, which determines how long an event type will be available after being published before it expires and is destroyed.

insertFieldDef Adds a field to an event type or a structure field.

isSystemDefined Returns true if the event type is a system-defined type that may not be altered.

orderFields Manages the order of the fields in an event type or structure field.

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

Method Description



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 {


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.



Getting Event Type Statistics

The BrokerAdminClient.getEventTypeStats method lets your client application obtain statistics for a particular event type definition. The statistics are returned as fields within a BrokerEvent.

After you have obtained the BrokerEvent containing the statistics, you can retrieve each field using the BrokerEvent.get<type>Field method, described in the webMethods Broker Client Java API Programmer’s Guide. The version of the get<type>Field method to be used will depend on the data type of field you are retrieving. The following example illustrates how to obtain a BrokerEvent containing an event type definition's statistics and extract the value of two fields.

. . . BrokerDate create_time; BrokerDate update_time; BrokerEvent e; BrokerAdminClient c; try {


client_group, "My Broker Monitor",null);

/* Get the BrokerEvent containing an event type’s statistics */ e = c.getEventTypeStats(“myEventType”); /* Get the time and date the event type definition was created */ create_time = e.getDateField( “createTime”); /* Get the time and date the event type definition was modified */ update_time = e.getDateField( “updateTime”);

} catch (BrokerException ex) { System.out.println("Error getting event type statistics\n"+ex); return;

} . . .

Creating and Modifying Event Type Definitions

Your client application can use the BrokerAdminClient.setEventAdminTypeDef method to modify an event type's definition. Your application must first obtain and modify (or create and initialize) the desired BrokerAdminTypeDef object and provide it as a parameter to this method.

If the event type represented by the BrokerAdminTypeDef object does not exist on the Broker, it will be created. If the event type already exists on the Broker, it will be updated.

The BrokerAdminClient.setEventTypesAndClientGroups method can also be used to set event types as well as client groups for a Broker.



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 the BrokerAdminTypeDef object for the event type */ def = new BrokerAdminTypeDef(“myEventType”,

BrokerTypeDef.FIELD_TYPE_EVENT);

/* Set two fields in the event type definition */ field1 = new BrokerAdminTypeDef(BrokerTypeDef.FIELD_TYPE_STRING); field2 = new BrokerAdminTypeDef(BrokerTypeDef.FIELD_TYPE_BOOLEAN);

/* Add the fields to the event type definition */ def.setFieldDef(“Name”, field1); def.setFieldDef(“Active”, field2);

/* Set the event type definition. * Note that if it doesn’t exist, it will be created. * If the event type definition does exist, it will be * replaced with the new version. */

c.setEventAdminTypeDef(def); } catch (BrokerException ex) {

System.out.println("Error creating/modifying event type def\n"+ex); return;

} . . .



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 {


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.



Event Type Infosets

The following BrokerClient methods, which are described in the webMethods Broker Client Java API Programmer’s Guide, allow you to retrieve event type infosets and infoset names:

The BrokerClient.getEventTypeInfoset method can be used to retrieve a specific infoset for a particular event type.

The BrokerClient.getEventTypeInfosets method can be used to retrieve all the infosets for a particular event type.

The BrokerClient.getEventTypeInfosetNames method can be used to retrieve all the infoset names for a particular event type.

Setting Event Type Infosets

Your client application can use the BrokerAdminClient.setEventTypeInfoset method to modify an event type's infoset. Your application must first obtain and modify (or create and initialize) a BrokerEvent object that represents the infoset and provide it as a parameter to this method, along with the event type name and infoset name. If your infoset name already exists for the event type name you specify, it will be updated. If it does not exist, it will be created.

Note: For information on event type name and infoset name restrictions, see the webMethods Broker Client Java API Programmer’s Guide.

Creating or Modifying Multiple Infosets

The BrokerAdminClient.setEventTypeInfosets method allows your client application to create or modify several infosets for a single event type definition in a one method invocation. You must supply an array of BrokerEvent objects that represent the infosets and the target event type name.

The name of each infoset will be taken from each BrokerEvent object's type name. If any of the infoset names already exist for the event type name you specify, they will be updated. If any of the infoset names do not exist, they will be created.

Destroying Infosets

You can use the BrokerAdminClient.destroyEventTypeInfoset method to destroy an infoset for an event type on the Broker to which your BrokerAdminClient is connected. You must supply the name of the event type and the name of the infoset you wish to destroy.

The following example illustrates how to use the destroyEventTypeInfoset method to destroy an infoset for an event type:





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.


2 Getting Started

Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44

Overview of the webMethods Broker Administration API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44

Using the Administration API for Java . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47

webMethods Broker Java API Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48


2 Getting Started

Overview

This chapter describes the basic features of the administration API for the webMethods Broker system. The API lets you create applications that automate the monitoring and management of your Information Brokers and Broker clients. You can also create applications that integrate your webMethods Brokers and Broker clients with existing network management systems.

After reading this chapter, you will be ready to learn how to use the webMethods Broker administration interfaces in your client applications.

Overview of the webMethods Broker Administration API

The webMethods Broker administration API allows your client applications to control and monitor the basic elements of the webMethods Broker system, including Broker Servers and the hosts on which they are running, Broker clients, client groups, event type definitions, SSL configurations, and tracing and logging functions. The following figure shows the elements that comprise a webMethods Broker system and their relationship to one another. For a complete list of attributes of Brokers, clients, client groups, and event types, see the webMethods Broker Client Java API Programmer’s Guide and Administering webMethods Broker.


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.


2 Getting Started

List all of the Brokers running within a particular Broker Server.

Obtain statistics for the host where a Broker Server is running.

Pause all publishing clients on a Broker Server.

Chapter 3, “Managing Brokers and Broker Servers” describes the use of this class to administer hosts where Brokers are running.

BrokerAdminClient

The BrokerAdminClient interface allows your client application to administer a Broker. The methods offered by this interface allow your client application to:

List information for all of the Broker clients connected to the Broker.

List all of the client groups and event types defined for the Broker.

Create, modify, and destroy client groups and event type definitions.

Obtain statistics for a Broker client, client group, event type, or a Broker.

Chapter 4, “Managing Broker Clients” and “Managing Client Groups” on page 75 describe the use of this interface to administer Broker clients and client groups. Chapter 1, “Managing Broker Event Types” covers the methods offered for managing event types.

Monitoring Brokers

The webMethods Broker system provides a variety of ways for your client applications to monitor a Broker's activity. Chapter 10, “Monitoring Broker Activity” describes the interfaces and events available to your client application for monitoring Brokers.

Managing Security Configurations

The BrokerAccessControlList, BrokerServerClient , BrokerAdminClient, and BrokerSSLConfigV2 interfaces allow your client application to control the security configuration for Broker Servers and Brokers. Chapter 6, “Managing Security Configurations”covers the interfaces offered for managing SSL configurations.

Managing Territories

webMethods Broker allows two or more Brokers to cooperate as a territory. The use of territories allows an event published by a client connected to one Broker to be forwarded to a client connected to a different Broker within the same territory.

You may also configure two Brokers so that they form a gateway between two different territories.


2 Getting Started

Chapter 7, “Managing Broker Territories” describes the interfaces you can use to configure and manage Broker territories.

Managing Clusters

webMethods Broker allows you to group two or more Brokers to form a cluster. The Brokers in a cluster share information about their event type definitions and client groups. The clusters can be configured with JMS load balancing policies for enabling client-side load balancing and failover. For more information, see the webMethods Messaging Programmer’s Guide.

You may also configure two Brokers so that they form a gateway between two different clusters.

Chapter 8, “Managing Broker Clusters” describes the interfaces you can use to configure and manage Broker clusters.

Managing Configurations

The webMethods Broker API for Java provides interfaces that allow you to load, store, import and export configuration information for Broker Servers, Brokers, Broker clients, client groups, and event types. These interfaces are described in Chapter 9, “Managing Site Configurations”.

Using the Administration API for Java

The webMethods Broker administration API is implemented as a Java package that provides all the necessary interfaces, classes and methods for creating administrative client applications.

Compatibility

This version of the webMethods Broker Java API, and applications developed with it, are compatible and fully inter-operable with Brokers and applications developed with the C, Java, and ActiveX APIs and webMethods 6.x and later.

Application Development with webMethods Broker

For information on application development, see the webMethods Broker Client Java API Programmer’s Guide.


2 Getting Started

Application Deployment

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

Note: These files must be in the application's CLASSPATH when the application is deployed.

The default location of the files required for application deployment are as follows:

webMethods Broker Java API Documentation

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

The default location of the webMethods Broker Javadoc is as follows:

Platform Default location

AIX, HP-UX, Linux, and Solaris

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

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

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

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

Platform Location of webMethods Broker Java Packages

AIX, HP-UX, Linux, and Solaris

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

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


3 Managing Brokers and Broker Servers

Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50

Understanding Broker Server Clients . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50

Managing a Broker Server Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52

Managing Brokers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55



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



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.



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

Un-Registering Callback Objects

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

Managing a Broker Server Configuration

Getting Broker Server Statistics

You can use the BrokerServerClient.getStats method to obtain statistics for the Broker Server to which your BrokerServerClient is connected. The statistics are returned as fields within a BrokerEvent.

After you have obtained the BrokerEvent containing the statistics, you can retrieve each field using the appropriate BrokerEvent.get<type>Field method, as described in the webMethods Broker Client Java API Programmer’s Guide. The following example illustrates how to obtain and parse the BrokerEvent containing the Broker Server's statistics.

. . . int num_connections; boolean low_disk_space; BrokerEvent e; BrokerServerClient c; try {

/* Create a Broker Server client */ c = new BrokerServerClient(broker_host, null);

/* Get the BrokerEvent containing the Broker Server’s statistics */ e = c.getStats(); /* Get the total number of connections */ num_connections = e.getIntegerField( “numConnections”);

connect_state Meaning

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

CONNECT_STATE_DISCONNECTED The client has been disconnected.

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



/* Get the disk space status */ low_disk_space = e.getBooleanField( “isDiskSpaceLow”); . . .

} catch (BrokerException ex) { System.out.println("Error getting host statistics\n"+ex); return;

} . . .

Getting System Usage Statistics

The BrokerServerClient.getUsageStats method allows you to obtain system usage statistics for the host to which your BrokerServerClient is connected.

After you have obtained the BrokerEvent containing the statistics, you can retrieve each field using the BrokerEvent.get<type>Field method, described in the webMethods Broker Client Java API Programmer’s Guide. The version of the get<type>Field method to be used will depend on the data type of the field you are retrieving. The following example illustrates how to obtain a BrokerEvent containing the system usage statistics and extract the value of two fields.

. . . long swap_space_total; long swap_space_free; BrokerEvent e; BrokerServerClient c; try {


/* Get the BrokerEvent containing the usage statistics */ e = c.getUsageStats(); /* Get the total amount of swap space */ swap_space_total = e.getLongField( “swapSpaceMax”); /* Get the swap space available */ swap_space_free = e.getLongField( “swapSpaceFree”); . . .

} catch (BrokerException ex) { System.out.println("Error getting usage statistics\n"+ex); return;

} . . .

Getting and Setting the Default Broker

You can use the BrokerServerClient.getDefaultBrokerName method to obtain the name of the default Broker on the Broker Server to which your BrokerServerClient is connected. If you do not specify a Broker name when you create a BrokerClient, as described in the webMethods Broker Client Java API Programmer’s Guide, your client will be connected to the default Broker.

You can use the BrokerServerClient.setDefaultBrokerName method to set the name of the default Broker.



The following example illustrates how to use the getDefaultBrokerName and setDefaultBrokerName methods to get and set the default Broker name.

. . . String broker_name; BrokerServerClient c; . . .

/* Create a Broker Server client */ c = new BrokerServerClient(broker_host, null); . . .

try { /* Get the default Broker name */ broker_name = c.getDefaultBrokerName();

} catch (BrokerException ex) { System.out.println("Error getting default Broker\n"+ex); return;

} try {

/* Set the default Broker name */ c.setDefaultBrokerName(“My Broker”); . . .

} catch (BrokerException ex) { System.out.println("Error setting default Broker\n"+ex); return;

} . . .

Getting and Setting Log Configuration

You can use the BrokerServerClient.getLogConfig method to obtain the logging configuration for a Broker Server and the BrokerLogConfig class represents logging configuration.

The BrokerServerClient.setLogConfig method allows you to set the logging configuration for a Broker Server.

Getting the Port Information

The BrokerServerClient.getActivePort method allows you to obtain the base port for the Broker Server to which your BrokerServerClient is connected. The base port is used for non-SSL connections and has a default value of 6849. The base port number is also used to calculate the port numbers as shown in the following table.

Port number Description

Base port number minus 1

Used for SSL connections without client authentication.

Base port number minus 2

Used for SSL connections with client authentication.



Getting and Setting the License

The BrokerServerClient.getLicense, and BrokerServerClient.getLicenseContent methods let you obtain the license details for the Broker Server to which your BrokerServerClient is connected.

The BrokerServerClient.setLicense, BrokerServerClient.setLicenseContent, and BrokerServerClient.setLicenseFile methods are used to set the license.

Note: For Broker Servers earlier than 8.0 version, the BrokerServerClient.getLicense method returns a string containing the Broker host's license.

Starting and Stopping the Host Process

You can use the BrokerServerClient.startServerProcess method to start the Broker Server process on the specified host. The stopProcess method is used to stop a Broker Server process.

The getServerProcessRunStatus method can be used to determine the state of the Broker Server process.

Managing Security Configurations

This topic is covered in Chapter 6, “Managing Security Configurations”.

Managing Brokers

The BrokerServerClient class provides several methods for monitoring and controlling Brokers. The BrokerAdminClient also offers a limited number of methods, described in “Broker Administration” on page 64, for monitoring a particular Broker.

Using Change Locks

If you have multiple client applications that want to manage a Broker, race conditions may result if more than one client attempts to update the Broker's configuration.

You can use the BrokerAdminClient.acquireChangeLock method to obtain a lock for the Broker to which a BrokerClient is connected. This method will return a BrokerChangeLock object with the variables shown in the following table.

Data Member Description

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



Your client application should use the BrokerAdminClient.releaseChangeLock method to release a Broker change lock, after it has finished updating the Broker.

Listing all Brokers on a Host

The BrokerServerClient.getBrokers method lets you obtain a list of all the Brokers running in the Broker Server to which your BrokerServerClient is connected. An array of BrokerInfo objects is returned and each element contains details such as a Broker's name, description, and territory information. This method is available to all Broker Server clients.

The following example illustrates how to list all Brokers in a Broker Server:

. . . int i; BrokerInfo brokers[]; BrokerServerClient c; try {

/* Create a Broker Server client */ c = new BrokerServerClient(broker_host, null); /* Get a list of all Brokers in this server and print them out*/ brokers = c.getBrokers(); for(i = 0; i < brokers.length; i++) {

System.out.println(brokers[i].broker_name+”\n”); }

} catch (BrokerException ex) { System.out.println("Error getting Broker list\n"+ex); return;

} . . .

String client_id; If acquired is 0 (false), this member will contain the ID of the client currently holding a lock on the Broker. Otherwise, this member will be set to NULL. For information on client IDs, see “Broker Client Administration” on page 66.

int session_id; If acquired is 0 (false), this member will contain the session ID of the client currently holding a lock on the Broker. Otherwise, this member will be set to zero.

BrokerDate lock_time If acquired is 0 (false), this member will contain the date and time the lock was acquired. Otherwise, this member will be set to NULL.




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


4 Managing Broker Clients

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

Understanding BrokerAdminClients . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60

Broker Administration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64

Broker Client Administration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66



Overview

This chapter describes how you can use the BrokerAdminClient interface to obtain information about Broker clients that are connected to a Broker. Reading this chapter should help you understand:

How to create and use a BrokerClient for administration purposes.

How to disconnect and reconnect an administrative BrokerClient.

How to obtain the identifiers of the Broker clients connected to a particular Broker.

How to obtain statistics for Broker clients connected to a Broker.

Getting or setting a Broker client's properties, including event subscriptions.

Destroying or disconnecting a Broker client.

Understanding BrokerAdminClients

The BrokerAdminClient class extends the BrokerClient class, described in the webMethods Broker Client Java API Programmer’s Guide. In addition to having access to all the BrokerClient methods, the BrokerAdminClient provides a wide array of methods for administering Information Brokers, Broker clients, client groups, and event type definitions. Your client program creates a BrokerAdminClient to monitor and control the operation of a particular Broker.

For example, a network monitoring application might create a BrokerAdminClient to:

Obtain usage statistics for a Broker, a particular Broker client, a client group, or an event type.

Obtain a list of a Broker's clients, client groups, and event type definitions.

Create or destroy a Broker client, client group, or event type definition.

Change the properties of a Broker client, client group, or event type definition.

This chapter focuses on administration methods related to Brokers and Broker clients. Chapter 5, “Managing Client Groups” describes the BrokerAdminClient methods for administering client groups and Chapter 1, “Managing Broker Event Types” describes the methods for administering event type definitions.

Creating a BrokerAdminClient

Creating a BrokerAdminClient will establish a connection between your application and a Broker. This connection is identified by the following tuple (an ordered set of values):

The name of the host where the Broker server is running.

The IP port number assigned to the Broker's server.

The name of the Broker.



Multiple Broker clients within a single application that connect to the same Broker will all share a single network connection.

Your application creates an administrative Broker client by using the BrokerAdminClient constructor and specifying these parameters:

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

The name of the Broker to which you wish to connect. You may specify a null value if you want to connect to the default Broker. The default Broker for a particular host is determined by your webMethods Broker administrator. It can also be set or obtained using the BrokerServerClient class, described in Chapter 3, “Managing Brokers and Broker Servers”. See “Listing all Brokers on a Host” on page 56 for details on obtaining the names of Brokers available on a given host.

A unique client ID that identifies your Broker client. You may specify a null value if you wish the Broker to generate a unique client ID for you. The client ID generated by the Broker can be obtained after this call completes by calling the BrokerClient.getClientId method, described in the webMethods Broker Client Java API Programmer’s Guide.

The client group for your new Broker client. Client groups define the event types your new Broker client will be able to publish or retrieve, as well as the life cycle and queue storage type for your Broker client. Client groups are defined by your webMethods Broker administrator. See Chapter 5, “Managing Client Groups” for information on using the BrokerAdminClient class to administer client groups.

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

A BrokerConnectionDescriptor to be used for the new Broker client. If you specify a null value, a new connection descriptor will be created for you. The BrokerConnectionDescriptor class is covered in detail in the webMethods Broker Client Java API Programmer’s Guide.

The following example illustrates how to create a new BrokerAdminClient object. In this example, a null Broker name is passed to indicate that the caller wishes to connect to the default Broker on the host "localhost". A null client ID is specified, indicating that the Broker should generate a unique client ID. A client group named "admin" is requested and the application name is set to "My Broker Monitor." A null connection descriptor is passed, indicating that the caller wishes a default connection to be established.

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

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

BrokerAdminClient c;



. . . /* Create an administrative client */ try {

c = new BrokerAdminClient(broker_host, broker_name, null, client_group, "My Broker Monitor", null);

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

return; }

. . .

Destroying a BrokerAdminClient

The following example shows the use of the BrokerAdminClient.destroy method, which is inherited from the BrokerClient class described in the webMethods Broker Client Java API Programmer’s Guide. The client state and event queue for the BrokerAdminClient that is being destroyed will also be destroyed.

. . . BrokerAdminClient c; . . . try {

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

System.out.println("Error destroying admin client\n"+ex); return;

} . . .

Using Multiple BrokerAdminClients

You may find that a number of programming situations are made easier by creating multiple BrokerAdminClient objects within a single application.

If your application needs to monitor several Brokers at once, you can use a separate client for each Broker.

Because different Broker clients can belong to distinct client groups, they can subscribe to and publish different event types and their administrative permissions may be different.

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

The webMethods Broker API allows you to disconnect a Broker client from a Broker without actually destroying the Broker client. This is only useful if your Broker client's life cycle is explicit-destroy because the client state for the Broker client and all queued events will have been preserved by the Broker. Any events received by the Broker for your Broker client while it was disconnected will remain in the Broker client's event queue. When your Broker client reconnects to the Broker, specifying the same client ID, it



can continue retrieving events from the event queue. Disconnecting and reconnecting can be particularly useful for applications that wish to do batch-style processing at scheduled intervals.

Disconnecting a BrokerAdminClient

You can disconnect your BrokerAdminClient by calling the disconnect method inherited from the BrokerClient class. If the Broker client's life cycle is destroy-on-disconnect, the client state and event queue storage will be destroyed by the Broker. If the Broker client's life cycle is explicit-destroy, the client state and event queue storage will be preserved by the Broker until the Broker client reconnects.

The following example illustrates how to disconnect a BrokerAdminClient:

. . . BrokerAdminClient c; . . . try {

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

System.out.println("Error disconnecting admin client\n"+ex); return;

} . . .

Reconnecting a BrokerAdminClient

You can reconnect a previously disconnected Broker client that has a life cycle of explicit-destroy by invoking the reconnectAdmin method and specifying the same client ID that was used when your client was last connected, as shown in the example below. The inherited BrokerClient.getClientId method is described in the webMethods Broker Client Java API Programmer’s Guide.

If the Broker client's life cycle is explicit-destroy, the client state and event queue storage will have been preserved by the Broker since previous invocation of the disconnect method.

The following example illustrates how to reconnect a BrokerAdminClient:

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

BrokerAdminClient c; String client_id; . . . /* Create an admin client */ try {

c = new BrokerAdminClient(broker_host, broker_name, null, client_group, "My Broker Monitor",null);

} catch (BrokerException ex) {



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


/* Create a Broker Admin client */ c = new BrokerAdminClient(broker_host, broker_name, null,

“admin”, “My_Broker_Monitor”);

/* Destroy a Broker */ c.destroyBroker( “My_Broker”); ...



} catch (BrokerException ex) { System.out.println("Error destroying Broker\n"+ex); return;

} . . .

Getting and Setting the Broker Description

You can obtain or set a Broker's description using the BrokerAdminClient.getBrokerDescription and BrokerAdminClient.setBrokerDescription methods.

Getting Broker Statistics

The BrokerAdminClient.getBrokerStats method allows you to obtain statistics for a Broker. The statistics are returned as fields within a BrokerEvent.

After you have obtained the BrokerEvent containing the statistics, you can retrieve each field using the BrokerEvent.get<type>Field method, described in the webMethods Broker Client Java API Programmer’s Guide. The version of the get<type>Field method to be used will depend on the data type of the field you are retrieving. The following example illustrates how to obtain a BrokerEvent containing the system usage statistics and extract the value of two fields.

. . . int num_clients; int num_event_types; BrokerDate create_date; BrokerEvent e; BrokerAdminClient c; try {



/* Get the BrokerEvent containing the Broker’s statistics */ e = c.getBrokerStats(); /* Get the time and date that the Broker was created */ create_date = e.getDateField( “createTime”); /* Get the number of connected clients */ num_clients = e.getIntegerField( “numClients”); /* Get the number of event type definitions */ num_event_types = e.getIntegerField( “numEventTypes”); . . .

} catch (BrokerException ex) { System.out.println("Error getting Broker statistics\n"+ex); return;

} . . .



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 {


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:



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++) {



} . . .



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:



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++) {



} . . .

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.



. . . BrokerClientInfo inf; BrokerAdminClient c; try {


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.



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.



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 {


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



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:



client_group, "My Broker Monitor",null); /* Destroy a particular Broker client */ c.destroyClientById(“A123”); . . .

} catch (BrokerException ex) { System.out.println("Error destroying BrokerClient\n"+ex); return;

} . . .

Client State Sharing

The BrokerAdminClient.setClientStateShareLimitById method can be used to set the state sharing limit of a Broker client with a specific client identifier. webMethods Broker allows Broker clients in different applications to share the same client state. Sharing client state allows several Broker clients, possibly running on different hosts, to handle events in a parallel, first-come, first-served basis. This provides both parallel processing and load balancing for event handling.

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

See the webMethods Broker Client Java API Programmer’s Guide for a thorough discussion of client state sharing.

Setting the Last-published Sequence Number

You can use the BrokerAdminClient.setClientLastPublishSequenceNumberById method to set the sequence number of the last event that the Broker client published. The Broker stores this sequence number and uses it to recognize and discard duplicate events which may be published by the Broker client.



Clearing a Broker Client's Queue

The BrokerAdminClient.clearClientQueueById method can be used to clear the event queue of a Broker client with a specific client identifier. See “Obtaining Broker Client Identifiers” on page 66 for information on discovering client identifiers at run time.

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

You can use the BrokerAdminClient.getClientStatsById method to obtain information about a Broker client's queue, such as the current number of bytes and the number of events in the queue.

Tip! To clear the event queues of all Broker clients on a Broker Server, use BrokerServerClient.pruneServerLog method. For more information see, BrokerServerClient.

Broker Client Subscriptions

Listing Subscriptions

You can use the BrokerAdminClient.getClientSubscriptionsById method to get a list of all subscriptions registered for a Broker client with a specific client identifier. An array of BrokerSubscription objects is returned that represents all the Broker client's subscriptions. The BrokerSubscription class is described in the webMethods Broker Client Java API Programmer’s Guide.

Testing the Existence of a Subscription

The BrokerAdminClient.doesClientSubscriptionExistById method can be used to determine if a subscription exists for a particular Broker client. To use this method you must specify the client identifier and the event type name. You must also specify a subscription filter if the subscription that you wish to match was created with a filter. The method will return true if the subscription exists.

Creating Subscriptions

The BrokerAdminClient.createClientSubscriptionById method can be used to register a subscription for the Broker client with a specified client identifier. You provide the client identifier and a BrokerSubscription object that describes the event subscription to be registered.

The BrokerAdminClient.createClientSubscriptionsById method can be used to create several event subscriptions for a Broker client in one method invocation. You provide the client identifier and an array of BrokerSubscription objects that describe the event subscriptions to be registered.



The BrokerSubscription class is described in the webMethods Broker Client Java API Programmer’s Guide.

Note: If any subscription specified by either of these methods has already been registered for the specified Broker client, the method will have no effect on that subscription.

Destroying Subscriptions

Use the BrokerAdminClient.destroyClientSubscriptionById method to destroy a subscription for the Broker client with a specified client identifier. You provide the client identifier and a BrokerSubscription object that describes the event subscription to be destroyed.

The BrokerAdminClient.destroyClientSubscriptionsById method can be used to destroy several event subscriptions for a Broker client in one method invocation. You provide the client identifier and an array of BrokerSubscription objects that describes the event subscriptions to be destroyed.

Getting Broker Client Statistics

The BrokerAdminClient.getClientStatsById method allows you to obtain statistics for a Broker client with a particular client identifier. The statistics are returned as fields within a BrokerEvent. You can retrieve each field using the BrokerEvent.get<type>Field method, described in the webMethods Broker Client Java API Programmer’s Guide. The version of the get<type>Field method to be used will depend on the data type of field you are retrieving.

The following example illustrates how to obtain the system usage statistics and extract the value of two fields. In this example, the client identifier is hard-coded. See “Obtaining Broker Client Identifiers” on page 66 for information on discovering client identifiers at run time.

. . . int events_published; int events_retrieved; BrokerEvent e; BrokerAdminClient c; try {


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;

} . . .



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.


5 Managing Client Groups

Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76

Listing Client Groups . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76

Listing Client Identifiers by Group . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77

Getting Client Group Statistics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77

Creating and Destroying Client Groups . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78

BrokerClientGroupInfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80

Controlling Event Publications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80

Controlling Event Subscriptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81

Controlling Group Access . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82



Overview

This chapter describes how you can use the BrokerAdminClient interface to obtain information about client groups defined for a Broker. Reading this chapter should help you understand:

How to list client groups defined for a particular Broker.

How to list all Broker clients belonging to a client group.

How to obtain statistics for client groups defined for a Broker.

How to create or destroy a client group.

How to get or set a client group's properties, including event subscription and publication permissions.

Note: Chapter 4, “Managing Broker Clients” describes how to create, disconnect, reconnect and destroy a BrokerAdminClient object. For more information on client groups and their features, see webMethods Broker Client Java API Programmer’s Guide.

Listing Client Groups

The BrokerAdminClient.getClientGroupNames method lets you obtain a list of all client group names known to the Broker to which your BrokerAdminClient is connected. This method is available for use by any BrokerAdminClient.

The following example illustrates how to list all client group names for a Broker:

. . . int i; String client_groups[]; BrokerAdminClient c; try {


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;

} . . .



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:



client_group, "My Broker Monitor",null); /* Get a list of all client IDs for a client and print them out */ client_ids = c.getClientIdsByClientGroup(“myGroup”); for(i = 0; i < client_ids.length; i++) {

System.out.println(client_ids[i]+”\n”); }

} catch (BrokerException ex) { System.out.println("Error getting client IDs by group\n"+ex); return;

} . . .

Getting Client Group Statistics

The BrokerAdminClient.getClientGroupStats method lets you obtain statistics for a client group. The statistics are returned as fields within a BrokerEvent.

After you have obtained the BrokerEvent containing the statistics, you can retrieve each field using the BrokerEvent.get<type>Field method, described in the webMethods Broker Client Java API Programmer’s Guide. The version of the get<type>Field method to be used will depend on the data type of field you are retrieving. The following example illustrates how to obtain a BrokerEvent containing a client group's statistics and how to extract the value of two fields.

. . . int events_published; BrokerDate create_time; BrokerEvent e; BrokerAdminClient c; try {



/* 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”);



. . . } catch (BrokerException ex) {

System.out.println("Error getting client group statistics\n"+ex); return;

} . . .

Creating and Destroying Client Groups

You can use the BrokerAdminClient.createClientGroup method to create a client group for the Broker to which your BrokerAdminClient is connected. When creating a client group, you must specify the following:

The Broker client group's name. For information on client group name restrictions, see the webMethods Broker Client Java API Programmer’s Guide.

The life cycle of the Broker client belonging to the group; see “Life Cycle” on page 78.

The queue storage type for the Broker clients belonging to this group; see “Storage Type” on page 79.

The following example illustrates how you can create a client group using the BrokerAdminClient class.



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.



Storage Type

The queue storage type associated with your Broker client's client group will determine the storage reliability of the events that are queued for a Broker client belonging to the group. The storage type is specified as one of the BrokerTypeDef.STORAGE_* values shown below.

Setting Client Group Descriptions

You can use the BrokerAdminClient.setClientGroupDescription method to set the description for a particular client group. You must supply the client group's name and the new description and your client must have permission to change the client group's information.

Note: For information on client group name restrictions, see the webMethods Broker Client Java API Programmer’s Guide.

Destroying Client Groups

The BrokerAdminClient.destroyClientGroup method allows your applications to destroy a client group defined for a particular Broker. If any existing Broker clients belong to the group, a BrokerDependencyException exception will be thrown and the client group will not be destroyed.

Value Description

LIFECYCLE_DESTROY_ON_DISCONNECT The Broker will destroy the client state whenever the connection between a Broker client and the Broker is lost.

LIFECYCLE_EXPLICIT_DESTROY The client state will be maintained if the Broker client is disconnected. Used for client applications that need to maintain state in the event of network or system failures.

Life Cycle Description

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

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



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:



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 {


client_group, "My Broker Monitor",null); /* Get event types that may be published by clients in this group.*/ publish_events = c.getClientGroupCanPublishList(“myGroup”);



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 {


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 {


client_group, "My Broker Monitor",null); /* Get event types to which Broker clients in * this client group may subscribe. */



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 {


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


6 Managing Security Configurations

Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84

Access Control Lists . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84

Broker Server Security Configurations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86

Client Group Security Configurations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87

Territory Security Configurations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88

Territory Gateway Security Configurations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89

Cluster Security Configurations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89

Cluster Gateway Security Configurations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90



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.



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.



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



BrokerSSLIdentity.getDN returns the Broker Server's SSL DN

BrokerSSLIdentity.getIssuerDN returns the SSL authenticator DN for the Broker Server's SSL certificate.

BrokerServerClient.getDNFromKeyStore and BrokerServerClient.getRootDNsFromTrustStore methods returns the SSL keystore and trust store information.

BrokerServerClient.getSSLStatus returns the Broker Server's SSL status. The BrokerSSLStatus class describes whether SSL is enabled, disabled, not supported, or if there is an error in the configuration.

Retrieving and Setting Broker Server ACLs

The BrokerServerClient.getAdminACL method allows you to obtain a Broker Server's ACL. This list represents the user names or the authenticator names of all the entities that may issue administrative requests using a BrokerServerClient object.

You can use the BrokerServerClient.getDNsFromCertFile method to obtain all of the DNs from a Broker Server's certificate file.

You can use the BrokerServerClient.getRootDNsFromCertFile method to obtain all of the issuer DNs from a Broker Server's certificate file.

The BrokerServerClient.setAdminACL method allows you to set the ACL for a Broker Server.

Client Group Security Configurations

Client groups can use the BrokerAccessControlList class to determine which entities are allowed to create a BrokerClient or BrokerAdminClient object that belongs to the group.

You can use the BrokerAdminClient.getClientGroupACL method to obtain the ACL for a particular client group. You must supply the name of the client group whose ACL you wish to obtain.

The BrokerAdminClient.setClientGroupACL method allows you to set the ACL for a particular client group.

Obtaining Security Information for Client Sessions

You can determine which Broker client sessions are using basic authentication or SSL by following these steps:

1 Use the BrokerAdminClient.getClientInfoById or getClientInfosById method to obtain a BrokerClientInfo object for the particular Broker client in which you are interested.

2 Examine each BrokerClientSession object contained in the BrokerClientInfo.sessions data member.



3 Examine the BrokerClientSession.encrypt_level and encrypt_version data members to determine if SSL is being used. If SSL authentication is being used without encryption, then these data members will not be set. Note that BrokerClientSession.encrypt_level is deprecated.

4 Examine the BrokerClientSession.ssl_certificate data member to determine the Broker client's DN. While a Broker must always authenticate itself to a Broker client, the client is not required to authenticate itself to Broker. This data member will not be set under those circumstances.

Territory Security Configurations

Setting Territory Security

The BrokerAdminClient.setTerritorySecurity method allows you to set the level of security and the type of authentication that is to be used in the territory. All Brokers in the territory must be properly configured for the new settings and the changes may take some time to be propagated throughout the territory.

When using this method, you must provide the type of authentication to be used, specified as one of the BrokerAdminClient.AUTH_TYPE_* values.

Important! Use this method with care because changing the security setting might cause the territory to become partially disconnected. For example, setting SSL authentication or encryption when one or more Brokers are not configured for SSL will cause the territory to become partially disconnected.

Territory ACLs

Brokers in a territory can use the BrokerAccessControlList class to authenticate Brokers that want to join the territory. ACLs are only checked when a Broker joins the territory.

You can use the BrokerAdminClient.getTerritoryACL method to obtain the ACL for the Broker's territory.

You can use the BrokerAdminClient.setTerritoryACL method to configure the ACL for the Broker's territory.



Territory Gateway Security Configurations


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.




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


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.


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.



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.


7 Managing Broker Territories

Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94

Using Territories . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94

Using Territory Gateways . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97



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.



Note: For information on territory name restrictions, see the webMethods Broker Client Java API Programmer’s Guide.

When the new territory is created, the Broker to which the administrative client is connected will become the first member of that territory.

Adding a Broker to an Existing Territory

You can use the BrokerAdminClient.joinTerritory method to add a Broker to an existing territory. You must provide the following arguments to this method:

The name of the remote Broker whose territory this Broker is to join.

The name of the Broker host where the remote Broker is running.

The Broker to which the administrative client is connected will be added to the remote Broker's territory.

Removing a Broker from a Territory

The BrokerAdminClient.leaveTerritory method lets you remove the Broker to which your BrokerAdminClient is connected from its territory. When a Broker leaves a territory, communication must take place between the Broker being removed and the other Brokers in the territory.

You must provide the following arguments to this method:

The number of milliseconds to wait for the operation to complete. You can specify -1 to indicate you do not wish the operation to be subject to a time-out.

An indication of whether or not the operation should be forced to complete, even if communication with the other Brokers in the territory exceeds the time limit.

You can use the BrokerAdminClient.removeBrokerFromTerritory method to remove a Broker from a territory. This function will not wait for the communication between the other Brokers in the territory to complete, but returns as soon as the removal process is initiated.


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.



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.



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.


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.



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.


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.



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.



The BrokerAdminClient.setTerritoryGatewaySharedEventTypes method allows you to set the complete list of shared event types for a territory gateway. The is_synchronized variable in each element of infos will be ignored.

Note: To configure gateway event type sharing, first save the can-subscribe settings on both sides of the gateway and then save the can-publish settings. It is important to set the can-subscribe settings before the can-publish settings and to set them in separate invocations of this function.

You can control the content of the events that are forwarded through the gateway by specifying a subscribe_filter. If event filtering by the gateway is not desired, the subscribe_filter member should be set to null. For more information of event filtering, see the webMethods Broker Client Java API Programmer’s Guide.

Note: When porting applications from an earlier release, be sure to set the subscribe filter to either a valid value or to NULL.

Obtaining Gateway Statistics

You can use the BrokerAdminClient.getTerritoryGatewayStats method to obtain statistics about a territory gateway. These statistics include information about the gateway Broker as well as information about the number of events that have been enqueued, forwarded, and received.

You must provide the name of the territory whose statistics are to be returned.

The statistics are returned as an event, for convenience. See getTerritoryGatewayStats on page 251 for a complete listing of the territory statistics that are available.

Maintaining a Connection Between Gateway Brokers

In network configurations where gateway Brokers are separated by a firewall, the firewall may terminate a connection if the connection remains idle for a long period of time. To prevent this from occurring between gateway Brokers, you can use the BrokerAdminClient.setTerritoryGatewayKeepAlive method. This method causes a gateway Broker to periodically issue "keep-alive" messages to the other Broker, preventing the connection between them from remaining idle too long.

Activating the Keep-Alive Feature between Gateway Brokers

To activate the keep-alive feature on a gateway Broker, you use the BrokerAdminClient.setTerritoryGatewayKeepAlive method and specify the following two parameters:

territory_name. The name of the territory where the remote gateway Broker resides.

KeepAlive. The number of seconds between the keep-alive messages. To disable gateway keep-alive feature, specify 0 seconds.



Be aware that BrokerAdminClient.setTerritoryGatewayKeepAlive method activates the keep-alive feature in one direction. That is, it instructs the Broker to which the BrokerAdminClient client is connected, to issue keep-alive messages to the gateway Broker in the other territory. It does not instruct the remote gateway Broker to issue keep-alive messages. To activate keep-alive messages in both directions, you must execute BrokerAdminClient.setTerritoryGatewayKeepAlive on both gateway Brokers.

To implement the keep-alive feature correctly, you must understand the conditions that cause the firewalls to drop a connection. (In most cases, you will need to coordinate with the network administrators at each end of the gateway to obtain information about the behavior of the firewalls.) Given this information, you can determine which gateway Broker must issue keep-alive messages (it may be both) and the frequency at which the messages need to be issued to prevent the connection from dropping.

Checking the Keep-Alive Settings for a Gateway Broker

To get the gateway Broker's current keep-alive setting for a particular territory, you use the BrokerAdminClient.getTerritoryGatewayKeepAlive method. This method returns the gateway Broker's current keep-alive interval (in seconds) for a given territory.

Pausing a Gateway Broker

To temporarily halt forwarding of events from one gateway Broker to another, you use the BrokerAdminClient.setTerritoryGatewayPause method. When you use this method, you specify the territory whose events you want to hold and set the pause parameter to true.

Once you pause the forwarding of events to a particular territory, the gateway Broker queues documents for that territory in an event-forwarding queue. The Broker does not resume forwarding events to the remote territory until event-forwarding is explicitly re-enabled.

Pausing Traffic in Both Directions

Be aware that the BrokerAdminClient.setTerritoryGatewayPause method halts the flow of traffic in one direction. That is, it stops the Broker to which the BrokerAdminClient client is connected from sending outbound messages to a specified territory. It does not halt the flow of inbound traffic to the gateway Broker from the remote territory. To halt both inbound and outbound between two gateway Brokers, you must execute BrokerAdminClient.setTerritoryGatewayPause on both Brokers.

Note that once you pause the forwarding queue for a territory, it remains paused even if the gateway Broker is restarted or the Broker Admin client disconnects.

Pausing Traffic to and from Multiple Territories

If a Broker serves as a gateway to multiple territories, and you want to pause outbound traffic to all of the territories, execute BrokerAdminClient.setTerritoryGatewayPause on the gateway Broker once for each remote territory.



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:



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.



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.


8 Managing Broker Clusters

Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 106

Using Clusters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 106

Using Cluster Gateways . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109



Overview

This chapter describes how your administrative client applications can create and manage Broker-to-Broker communication through clusters and cluster gateways.

Using Clusters

The webMethods Broker systems allows two or more Brokers to share information about their event type definitions and client groups. This sharing of information enables communication between Broker clients connected to different Brokers.

Note: A Broker may be a member of no more than one cluster. However, clusters can be linked together using cluster gateways. For more information, see “Using Cluster Gateways” on page 109.

To share information and forward events, Brokers must join a cluster. A Broker can only belong to one cluster and all Brokers within the same cluster have knowledge of one another's event type definitions and client groups. The Brokers in a cluster do not forward documents to other Brokers in the cluster. For more information on this feature, see Administering webMethods Broker.

Creating a New Cluster

The BrokerAdminClient.createCluster method allows you to create a new cluster. You must provide the name of the cluster to be created.

Note: For information on cluster name restrictions, see the webMethods Broker Client Java API Programmer’s Guide.

When the new cluster is created, the Broker to which the administrative client is connected will become the first member of that cluster.

Adding a Broker to an Existing Cluster

You can use the BrokerAdminClient.addBrokerToCluster method to add a Broker to an existing cluster. You must provide the following arguments to this method:

The name of the remote Broker whose cluster this Broker is to join

The name of the Broker host where the remote Broker is running

The Broker to which the administrative client is connected will be added to the remote Broker's cluster.



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.


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.


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.



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.


For information on cluster security, see “Cluster Security Configurations” on page 89.



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.


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



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.



The BrokerAdminClient.setClusterGatewaySharedEventTypes method allows you to set the complete list of shared event types for a cluster gateway. The is_synchronized variable in each element of infos will be ignored.

Note: To configure gateway event type sharing, first save the can-subscribe settings on both sides of the gateway and then save the can-publish settings. It is important to set the can-subscribe settings before the can-publish settings and to set them in separate invocations of this function.

You can control the content of the events that are forwarded through the gateway by specifying a subscribe_filter. If event filtering by the gateway is not desired, the subscribe_filter member should be set to null. For more information of event filtering, see the webMethods Broker Client Java API Programmer’s Guide.

Note: When porting applications from an earlier release, be sure to set the subscribe filter to either a valid value or to NULL.

Obtaining Gateway Statistics

You can use the BrokerAdminClient.getClusterGatewayStats method to obtain statistics about a cluster gateway. These statistics include information about the gateway Broker as well as information about the number of events that have been enqueued, forwarded, and received. You must provide the name of the cluster and the name of the cluster gateway Broker.

The statistics are returned as an event, for convenience. See getClusterGatewayStats for a complete listing of the cluster statistics that are available.

Maintaining a Connection Between Gateway Brokers

In network configurations where gateway Brokers are separated by a firewall, the firewall may terminate a connection if the connection remains idle for a long period of time. To prevent this from occurring between gateway Brokers, you can use the BrokerAdminClient.setClusterGatewayKeepAlive method. This method causes a gateway Broker to periodically issue "keep-alive" messages to the other Broker, preventing the connection between them from remaining idle too long.

Activating the Keep-Alive Feature between Gateway Brokers

To activate the keep-alive feature on a gateway Broker, you use the BrokerAdminClient.setClusterGatewayKeepAlive method and specify the following three parameters:

cluster_name. The name of the cluster where the remote gateway Broker resides

Broker name. The name of the Broker belonging to the cluster specified by the cluster_name.



KeepAlive. The number of seconds between the keep-alive messages. To disable gateway keep-alive feature, specify 0 seconds.

Be aware that BrokerAdminClient.setClusterGatewayKeepAlive method activates the keep-alive feature in one direction. That is, it instructs the Broker to which the BrokerAdminClient client is connected, to issue keep-alive messages to the gateway Broker in the other cluster. It does not instruct the remote gateway Broker to issue keep-alive messages. To activate keep-alive messages in both directions, you must execute BrokerAdminClient.setClusterGatewayKeepAlive on both gateway Brokers.

To implement the keep-alive feature correctly, you must understand the conditions that cause the firewalls to drop a connection. (In most cases, you will need to coordinate with the network administrators at each end of the gateway to obtain information about the behavior of the firewalls.) Given this information, you can determine which gateway Broker must issue keep-alive messages (it may be both) and the frequency at which the messages need to be issued to prevent the connection from dropping.

Checking the Keep-Alive Settings for a Cluster Gateway Broker

To get the gateway Broker's current keep-alive setting for a particular cluster, you use the BrokerAdminClient.getClusterGatewayKeepAlive method. This method returns the gateway Broker's current keep-alive interval (in seconds) for a given cluster.

Pausing a Gateway Broker

To temporarily halt forwarding of events from one gateway Broker to another, you use the BrokerAdminClient.setClusterGatewayPause method. When you use this method, you specify the cluster whose events you want to hold and set the pause parameter to true.

Once you pause the forwarding of events to a particular cluster, the gateway Broker queues documents for that cluster in an event-forwarding queue. The Broker does not resume forwarding events to the remote cluster until event-forwarding is explicitly re-enabled.

Pausing Traffic in Both Directions

Be aware that the BrokerAdminClient.setClusterGatewayPause method halts the flow of traffic in one direction. That is, it stops the Broker to which the BrokerAdminClient client is connected from sending outbound messages to a specified cluster. It does not halt the flow of inbound traffic to the gateway Broker from the remote cluster. To halt both inbound and outbound between two gateway Brokers, you must execute BrokerAdminClient.setClusterGatewayPause on both Brokers.

Note that once you pause the forwarding queue for a cluster, it remains paused even if the gateway Broker is restarted or the Broker Admin client disconnects.



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.



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.



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.


9 Managing Site Configurations

Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 118

Collection Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 118

Server Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 118

Broker Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 119

Client Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 120

Client Group Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121

Event Type Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122

Territory Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122

Territory Gateway Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123



Overview

This chapter describes the webMethods Broker Java interfaces that allow you to load, store, import and export site configuration information for the following:

Broker Servers

Brokers

Clients

Client groups

Event types

Territories

Territory gateways

These interfaces work in conjunction with the ActiveWorks Definition Language (ADL), described in Administering webMethods Broker.

Note: See the webMethods Broker Client Java API Programmer’s Guide for information on naming restrictions for Brokers, client groups, event types, and territories

Collection Information

The BrokerCompleteCollection class can hold information about an entire configuration of Broker Servers, Brokers, Broker clients, client groups, event types, and access control lists.

The following table shows the methods offered by the BrokerCompleteCollection class.

Server Information

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

Method Description

read

readFile

Creates a BrokerCompleteCollection and initializes it from input data or from an input file containing ADL.

toString Returns a string of ADL that describes the collection defined by this object.

write Writes the contents of this collection, usually to a file, in ADL format.

writeVersionNumber Writes just the version number of this object.



Access Control List

Brokers contained in the server

Server's description

Server's host name

Server's license key

Server's log configuration

Port number used

Server's SSL configuration

The following table shows the methods offered by the BrokerCompleteServer class.

Broker Information

You can use the BrokerCompleteBroker class to hold information about a particular Broker. The following information is stored for the Broker:

Broker's name

Names of other Brokers in the Broker's territory

Method Description

deepRefresh Refreshes this object's data members, using the specified administrative Broker client.

deepRetrieve Returns a BrokerCompleteServer object initialized using the specified administrative Broker client.

deepStore Stores the information contained in this object into a Broker Server.

refresh Refreshes this object's data members, using the specified administrative Broker client. Any information the Broker client does not have permission to access will not be set.

retrieve Returns a BrokerCompleteServer object initialized using the specified administrative Broker client. Server information is returned, but not information on the server's Brokers.

store Stores the information contained in this object into a Broker Server. Server information is stored, but not information the server's Brokers.

toString Returns a string of ADL that describes the information contained in this object.




Client groups

Clients

Broker's description

Event types

An indication if this is the default Broker

Broker's territory name

The following table shows the methods offered by the BrokerCompleteBroker class.

Client Information

You can use the BrokerCompleteClient class to hold information about a particular Broker client. The following information is stored for the Broker client:

BrokerClientInfo for the Broker client

Broker client's infoset

Broker client's event subscription list

An indication of whether or not the Broker client's event subscription list should be overwritten when the store method is invoked.

The following table shows the methods offered by the BrokerCompleteClient class.

Method Description

deepRefresh Refreshes this object's data members, using the specified administrative Broker client.

deepRetrieve Returns a BrokerCompleteBroker object initialized using the specified administrative Broker client.

deepStore Stores the information contained in this object into a Broker.


retrieve Returns a BrokerCompleteBroker object initialized using the specified administrative Broker client.

store Stores most of the information contained in this object into a Broker Server.





Client Group Information

You can use the BrokerCompleteClientGroup class to hold information about a particular client group. The following information is stored for the client group:

Client group's Access Control List

Names of event types this group can publish

Names of event types to which this group can subscribe

ClientGroupInfo

An indication if errors should be ignored when using the store or deepStore methods

An indication if the can-publish and can-subscribe lists should be replaced when using the store or deepStore methods

The following table shows the methods offered by the BrokerCompleteClientGroup class.

Method Description


retrieve Returns a BrokerCompleteClient object initialized using the specified administrative Broker client.

store Stores most of the information contained in this object into the Broker client.



Method Description


retrieve Returns a BrokerCompleteClientGroup object initialized using the specified administrative Broker client.

store Stores the information contained in this object into the Broker.





Event Type Information

You can use the BrokerCompleteEventType class to hold information about a particular event type. The following information is stored for the event type:

Event types infosets

Event type's type definition

An indication if the definition should be replaced when using the store or deepStore methods

The following table shows the methods offered by the BrokerCompleteEventType class.

Territory Information

You can use the BrokerCompleteTerritory class to hold information about a territory of Brokers. For more information about territories, see “Managing Broker Territories” on page 93.

The following information is stored for territory:

Territory's Access Control List

Names of the Brokers that belong to the territory

BrokerTerritoryInfo, which contains a variety of information on the gateway, including its name, authentication type, and encryption level

The following table shows the methods offered by the BrokerCompleteTerritory class.

Method Description


retrieve Returns a BrokerCompleteEventType object initialized using the specified administrative Broker client.




Method Description




Territory Gateway Information

You can use the BrokerCompleteTerritoryGateway class to hold information about a territory gateway. For more information about territory gateways, see “Managing Broker Territories” on page 93.

The following information is stored for a gateway:

The gateway's Access Control List

The names of all the shared event types that can be forwarded to the remote half of the territory gateway

The names of all the shared event types that can be received from the remote half of the territory gateway

BrokerTerritoryGatewayInfo, which contains the territory's name, authentication type, and encryption level

The following table shows the methods offered by the BrokerCompleteTerritoryGateway class.

retrieve Returns a BrokerCompleteTerritory object initialized using the specified administrative Broker client.




Method Description


retrieve Returns a BrokerCompleteTerritory object initialized using the specified administrative Broker client.




Method Description


10 Monitoring Broker Activity

Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 126

Activity and Trace Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 126

Activity Traces . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 134

Broker Logging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 135

Broker Server Logs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 137



Overview

This chapter describes several ways that you can monitor the activity of a Broker. Reading this chapter will help you understand:

The activity and trace events published by a Broker to which your client application can subscribe

How you use the BrokerAdminClient and BrokerTraceEvent interfaces to obtain a Broker's activity traces

How to use the BrokerLogConfig and BrokerLogEntry classes to configure the Broker's activity log

How to access and manipulate Broker Server log entries

Activity and Trace Events

The webMethods Broker system provides two sets of events that provide information about changes in a Broker; activity events and trace events. Activity events describe changes in a Brokers clients, client groups, event types, and territory affiliation. Trace events provide information about the enqueuing, publishing, and forwarding of events performed by a Broker. Administrative tools or clients that dynamically adapt to changes in a Broker's configuration are two examples of applications that may want to subscribe to these events.

Each of the activity and trace event types described in this section are only published by a Broker if at least one client has subscribed to that event type. Any client with the necessary permissions may subscribe to these events and some of them can degrade the performance of your system, so you may want to consider restricting non-administrative applications from subscribing to them.

Note: An activity or trace event can only be received by a Broker client connected to the Broker which published the event. Activity and trace events are local and will never be forwarded to another Broker. Furthermore, activity traces cannot be subscribed to using a wildcard subscription. See the webMethods Broker Client Java API Programmer’s Guide for information on subscriptions and wildcards.

For information on configuring event subscription permissions, see Administering webMethods Broker.

Note: Events are known as documents in Administering webMethods Broker.

Activity Events

Activity events provide information about the change in a Broker's configuration. These changes involve:



Creation, disconnection, re-connection, destruction, client queue locking or unlocking for Queue Manipulation of a Broker client.

Creation, modification, or destruction of a client group.

Creation, modification, or destruction of an event type definition.

A Broker joining or leaving a territory. For more information on territories, see “Managing Broker Territories” on page 93.

Client Changes

The event type Broker::Activity::ClientChange provides information about a change in a Broker's clients. This event consists of the event fields shown in the following table.

Client Group Changes

The event type Broker::Activity::ClientGroupChange provides information about a change in a Broker's client groups. This event consists of the event fields shown in the following table.

Field Name Type Description

clientId unicode_string The identifier of the Broker client whose state has changed.

clientGroup unicode_string The Broker client's group affiliation.

appName unicode_string The application name associated with the Broker client.

stateFlags int A bit mask with one or more of the following values:

1-created

2-destroyed

4-connected

8-disconnected

16-client queue locked

32-client queue unlocked

user unicode_string The user that made the change. This will only be set if the entity making the change used an SSL connection.

authenticator unicode_string The entity that authenticated the user. This will only be set if the entity making the change used an SSL connection.



Event Type Changes

The event type Broker::Activity::EventTypeChange provides information about a change in a Broker's event type definitions. This event consists of the event fields shown in the following table.

Territory Changes

The event type Broker::Activity::TerritoryChange provides information about a change in a Broker's territory affiliation. This event will be published by a Broker when another Broker joins or leaves its territory. The event consists of the event fields shown in the following table.


created unicode_string[] The list of client groups that were created.

changed unicode_string[] The list of client groups that were changed. Changes may include modifications to the can-publish list, can-subscribe list, or ACL.

destroyed unicode_string[] The list of client groups that were destroyed.

changeTime date The time the change occurred.

user unicode_string The user that made the change.

authenticator unicode_string The entity that authenticated the user.


created unicode_string[] The list of event types that were created.

defChanged unicode_string[] The list of event types whose definitions were changed.

infoChanged unicode_string[] The list of event types whose infosets were modified.

destroyed unicode_string[] The list of event types that were destroyed.

changeTime date The time the change occurred.




territoryName unicode_string The name of the Broker's territory.

brokerName unicode_string The name of the Broker.



Trace Events

Trace events provide information about events that are passing through the system and are useful in monitoring and evaluating event traffic. Trace events themselves never cause other trace events to be generated, yet they may still add considerable overhead to your system. The same information is available through the getActivityTraces method, which will not degrade the performance of your system. Each trace event type is published only if at least one client has subscribed to that event type.

Note: Traces cannot be subscribed to using a wildcard subscription. See the webMethods Broker Client Java API Programmer’s Guide for information on subscriptions and wildcards.

Dropped Events

The event type Broker::Trace::Drop is published whenever an event was discarded by the Broker because it was delivered to a Broker client which did not have permission to receive the event. This event consists of the event fields shown in the following table.

hostName unicode_string The name of the Broker's host.

changeFlags int A bit mask with one or more of the following values:

1-jointed

2-left

4-local Broker




clientId unicode_string The Broker client's identifier.

eventTypeName unicode_string The name of the event type.

eventId long The event identifier from the event.

pubId unicode_string The identifier of the Broker client that delivered the event.

destId unicode_string The identifier of the intended recipient Broker client.

trackId unicode_string The tracking identifier from the event.

tag int The event's tag field.

eventByteSize int The size of the event in bytes.




Remotely Dropped Events

The event type Broker::Trace::RemoteDrop is published whenever an event was discarded by the Broker while forwarding to other territory Brokers because the event was too large to be handled by the territory Broker. This occurs in a territory consisting of 5.0 and pre 5.0 Brokers while forwarding an event of size greater than the maximum transaction size from 5.0 Broker to pre 5.0 Brokers. This event consists of the event fields shown in following table.

Enqueued Events

The event type Broker::Trace::Enqueue is published whenever the Broker places an event in a Broker client's queue. This event consists of the event fields shown in the following table.


brokerName unicode_string The name of the remote Broker for which the event was enqueued.

brokerHost unicode_string The host name where the remote Broker is running.



















Remotely Enqueued Events

The event type Broker::Trace::EnqueueRemote is published whenever the Broker puts an event in a remote Broker's queue as part of Broker-to-Broker communication. This event consists of the event fields shown in the following table.

Published Events

The event type Broker::Trace::Publish is published whenever the Broker publishes or delivers an event. This event consists of the event fields shown in the following table.






















Remotely Published Event

The event type Broker::Trace::PublishRemote is published whenever the Broker receives a published event from a remote Broker. This event consists of the event fields shown in the following table.

Received Events

The event type Broker::Trace::Receive is published whenever a Broker client acknowledges an event that it has retrieved from its client queue. This event consists of the event fields shown in the following table.















pubId unicode_string The identifier of the Broker client that published the event.







Remotely Received Event

The event type Broker::Trace::ReceiveRemote is published whenever a remote Broker acknowledges the receipt of a forwarded event. This event consists of the event fields shown in the following table.

Peek Events

The event type Broker::Trace::Peek is published whenever an event is peeked administratively from the Broker client's queue. This event consists of the event fields shown in the following table.


brokerName unicode_string The name of the remote Broker.




pubId unicode_string The identifier of the Broker client that published the event.









lockingId unicode_string The identifier of the Broker client that is holding a queue lock on this client.






Insert Events

The event type Broker::Trace::Insert is published whenever an event is inserted administratively into the Broker client's queue. This event consists of the event fields shown in the following table.

Delete Events

The event type Broker::Trace::Delete is published whenever an event is deleted administratively from the Broker client's queue. This event consists of the event fields shown in the following table.

Activity Traces

Each Broker maintains its own set of activity traces. Activity traces require very little overhead and will not degrade the performance of your system. However, activity traces can be lost if the Broker is very busy or if your client does not retrieve them quickly enough.

A BrokerTraceEvent is created by a Broker whenever one of the following occurs:








eventByteSize Int The size of the event in bytes.











A Broker client or remote Broker is created or destroyed.

A Broker client or remote Broker publishes or delivers an event.

A Broker client or remote Broker retrieves an event from its event queue.

A Broker adds an event to a client's or remote Broker's event queue.

An event was dropped from a Broker client's queue because the client did not have permission to receive the event.

Understanding the BrokerTraceEvent

The BrokerTraceEvent class represents an entry in a Broker's activity trace. Some of the information that may be contained in a trace event includes:

A key indicating the trace event's type

The name of the client application

The name of the Broker Server

The name of the Broker host

The application's client group and client identifier, if applicable

The event type name

The event's _env.tag field, destination ID, and receiving client ID

The client identifier of the destination client, if applicable

Obtaining Activity Traces

You can use the BrokerAdminClient.getActivityTraces method to obtain an array of BrokerTraceEvent objects. You must supply the sequence number of the first trace event to be retrieved and the number of milliseconds to wait if no trace information is available.

The first time you invoke this method, the sequence number should be set to zero. On subsequent invocations of this method, you should set the sequence number one plus the value of the last trace event's sequence number.

Broker Logging

Each Broker maintains a log containing three levels of failure messages, which may be configured individually.

Level Description

Alert Identifies critical messages.

Warning Identifies important messages.



The Broker's log may use any of the following logging mechanisms:

Unix syslog facility

Windows NT event log

SNMP alerts

Understanding the BrokerLogConfig

You can use the BrokerServerClient.getLogConfig method to obtain the logging configuration for a Broker Server. The BrokerServerClient.setLogConfig method allows you to set the logging configuration for a Broker Server.

The BrokerLogConfig class represents the Broker Server's logging configuration and provides methods that allow you to:

Obtain log configuration entries by topic.

Obtain the entire contents of the log configuration.

Remove a single entry from the log configuration or remove all entries.

Remove log configuration entries by topic

The following table shows the methods offered by the BrokerLogConfig class.

Informational Identifies informational messages.

Method Description

clearLogOutput

clearLogOutputs

Clears one or more entries from a specified log output.

clearLogTopic

clearLogTopics

Clears one or more entries from a specified log topic.

getLogOutput

clearLogOutputs

Returns one or more BrokerLogEntry objects which represent the state of the specified log output or outputs.

getLogTopic

getLogTopics

Returns one or more BrokerLogEntry objects which represent the state of the specified log topic or topics.

setLogOutput Sets the value of a log output's state.

setLogTopic Sets the value of a log topic's state.

toString Returns a string containing the log configuration in a human-readable format.

Level Description



Understanding the BrokerLogEntry

The BrokerLogConfigEntry class represents the settings for an instance of a log output or a log topic. It contains the following information:

The type of log output or topic being represented.

An indication of whether or not the output or topic is enabled.

An optional string containing additional information.

Broker Server Logs

Each Broker Server maintains a log of significant events that have occurred. The format of each entry described by the BrokerServerLogEntry object is shown in the following table.

Each Broker Server log entry is assigned a type as defined in the following table.

Obtaining Log Entries

You can use the BrokerServerClient.getServerLogEntries method to obtain a desired set of entries from the log of the Broker Server to which your client is connected. This method lets you specify the date of the first entry in which you are interested and the total number of entries you wish to retrieve.

Note: Attempting to obtain all server log entries may create performance problems and may use up significant amounts of memory.


time_stamp BrokerDate The date and time that the entry was created.

entry_type short The entry's type. See the next table, below, for a list of possible types.

entry_mesg_id short The message identifier.

entry_msg_text char * The event identifier from the event.

Constant Description

SERVER_LOG_MESSAGE_UNKNOWN The entry has an undefined type.

SERVER_LOG_MESSAGE_INFO The entry contains an informational message.

SERVER_LOG_MESSAGE_WARNING The entry contains a warning message.

SERVER_LOG_MESSAGE_ALERT The entry contains an alert message.



The BrokerServerLogEntry.toString method allows you to convert a BrokerServerLogEntry to a character string.

Obtaining Log Information

The BrokerServerLogInfo object describes basic information about a particular server's log. The following table describes the contents of the BrokerServerLogInfo object.

You can use the BrokerServerClient.getServerLogStatus method to obtain the status of the log of the Broker Server to which your client is connected.

Deleting Log Entries

You can use the BrokerServerClient.pruneServerLog method to delete selected entries from the log of the Broker Server to which your client is connected. All entries with dates equal to or older than the date you specify will be deleted.


num_entries int The number of entries contained in the log.

first_entry BrokerDate The date and time of the earliest entry contained in the log.

last_entry BrokerDate The date and time of the most recent entry contained in the log.


11 Queue Browser

Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 140

Client Queue Browser . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 140

Using Client Queue Browser . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 141

Forwarding Queue Browser . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 142

Using Forwarding Queue Browser . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 144

BrokerAdminClient . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 145

BrokerClient . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 145

BrokerQueueBrowser and BrokerClientQueueBrowser . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 146

BrokerLockedQueueBrowser and BrokerLockedClientQueueBrowser . . . . . . . . . . . . . . . . . . . . 147

Creating and Closing Client Queue Browsers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 148

Creating and Closing Forwarding Queue Browsers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 151

Acquiring a Queue Lock . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 153

Releasing a Queue Lock . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 153

Queue Position . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 153

Filters on a Queue Browser . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 154

Viewing Queue Content . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 158

Rearranging Queue Content . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 166


11 Queue Browser

Overview

This chapter describes several ways by which you manage client queues. Reading this chapter will help you understand:

How to use BrokerQueueBrowser, BrokerLockedQueueBrowser, BrokerQueueBrowserInfo, and BrokerClient and BrokerAdminClient classes to examine a queue's content.

How to rearrange the contents of the client queue by adding, deleting, and replacing documents.

How to rearrange the contents of the forwarding queue for a remote Broker by adding, deleting, and replacing documents.

Note: Broker events are called Broker documents types in Software AG Designer and other webMethods components.

Client Queue Browser

webMethods Broker Java API 5.x and 6.1 provided the queue manipulation API with a limited ability to manipulate the contents of a client queue. In webMethods Broker Java API 6.5 and later, the queue manipulation API is replaced with the client queue browser API, which supports queue management in a much more robust manner. The following are the key differences between the new queue browser and the former queue manipulation feature.

The client queue browser supports three distinct modes of operation:

1 A client can inspect its own queue contents without requiring any administrative privileges.

2 An administrative client can inspect a client queue without acquiring the client's queue lock.

3 An administrative client can acquire a queue lock and perform an "in-place" replacement of documents in the locked queue, in addition to the usual insert, delete and browse operations.

You can perform four operations with the queue browser. Note that you can only perform the last three operations on a locked queue.

1 The browse operation to return queued documents, including the documents that have been retrieved but are not yet acknowledged (i.e., "unacknowledged") documents. You can apply filtering on browse operations.

2 The insert operation to add documents to either the head or tail of a locked queue.

3 The delete operation to delete documents based on their receipt sequence numbers.


11 Queue Browser

4 The modify operation to replace documents "in-place" based on their receipt sequence numbers.

Using Client Queue Browser

Client queue browser works in three different modes.

1 Client queue browser. A client can open a queue browser on its own queue and browse documents without requiring any administrative privileges. A client queue browser requires a dedicated client session and allows browse operations on the queue from any queue position and exposes all documents in the queue.

2 Administrative Queue Browser - Unlocked Mode. An administrative queue browser allows an administrative client to access the contents of a client queue owned by a different client at runtime. In the unlocked browse mode the client queue is not locked, meaning that the queue content could change between queue browser operations. In this unlocked mode, queue browsing is the only operation the administrative client can perform. The existence of an administrative queue browser in an unlocked mode does not impact the normal functioning of the client queue.

3 Administrative Queue Browser - Locked Mode. An administrative queue browser allows an administrative client to access the contents of a client queue owned by a different client at runtime. In this mode, the client queue is locked for the lifetime of the queue browser. You can browse queue contents, delete documents from queue, insert new documents into the queue, and modify documents in the queue.

In order to invoke any queue browser operation on a client queue, you must first create a client queue browser using one of the following methods:

BrokerClient.createClientQueueBrowser()

Broker client creates a queue browser to browse its own queue.

BrokerAdminClient.createClientQueueBrowser()

Broker administrative client creates a queue browser to browse another client's queue

BrokerAdminClient.createLockedClientQueueBrowser()

Broker administrative client creates a queue browser to manipulate the contents of another client's queue.

These functions will return a queue browser that can be used to invoke various queue management functions on the client queue.

Note: Pre-6.5 Brokers do not support the queue browser API. You will receive an error if your client attempts to open a queue browser on pre-6.5 versions of Broker clients.

The BrokerClientQueueBrowserInfo object represents information of a client queue browser with data members described in the following table.


11 Queue Browser

Forwarding Queue Browser

webMethods Broker Java API 8.1 and later provides an API to view the contents of a forwarding queue for a remote Broker. The forwarding queue browser supports two distinct modes of operation:

1 An administrative client can inspect a forwarding queue without acquiring the client's queue lock.

2 An administrative client can acquire a queue lock and perform browse, delete, insert, and modify operations.

You can perform four operations with the queue browser. Note that you can only perform the last three operations on a locked queue.

1 The browse operation to return queued documents, including the documents that have been retrieved but are not yet acknowledged (i.e., "unacknowledged") documents. You can apply filtering on browse operations.

2 The insert operation to add documents to the tail of a locked queue.

Note: You cannot insert documents to the head of a forwarding queue for a remote Broker.

3 The delete operation to delete documents based on their receipt sequence numbers.

4 The modify operation to replace documents "in-place" based on their receipt sequence numbers.

In addition to regular documents, the forwarding queue for a remote Broker might also contain internal events that Broker uses to perform tasks such as territory synchronization, and subscription updates. Internal events are produced only by Brokers and consumed only by peer Brokers in a territory, cluster, or a gateway Broker. Regular


String clientId This member contains the ID of the client on which the queue browser is currently open. For information on client IDs, see “Queue Browser” on page 139.

String browserId This member contains the ID of the client that created the queue browser. For information on client IDs, see “Queue Browser” on page 139.

int browserSessionId

This member contains the session ID of the client that created the queue browser.

boolean locked The value is set to true if the client queue is locked by this queue browser; otherwise, false.

int createTime This member contains the date and time when the queue browser was created.


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.


11 Queue Browser

In this illustration, if you set the cursor position to "2" and request six events, the queue browser returns only four events namely, Regular Event 3, Regular Event 4, Regular Event 5, and Regular Event 6. This behavior occurs because the events at cursor position 2 and cursor position 3 are internal events. The queue browser skips these events and returns the remaining events from the forwarding queue.

You can delete regular events from the forwarding queue for a remote Broker, but you cannot delete internal events. An internal event might contain metadata changes. So deleting an internal event would mean that the regular events that come next in the queue might not be consumed successfully by the subscribers due to metadata mismatch.

Using Forwarding Queue Browser

Forwarding queue browser works in two modes.

1 Administrative Queue Browser - Unlocked Mode. An administrative queue browser allows an administrative client to access the contents of a forwarding queue for a remote Broker at runtime. In the unlocked browse mode the forwarding queue is not locked, meaning that the queue content could change between queue browser operations. In this unlocked mode, queue browsing is the only operation the administrative client can perform. The existence of an administrative queue browser in an unlocked mode does not impact the normal functioning of the forwarding queue.

2 Administrative Queue Browser - Locked Mode. An administrative queue browser allows an administrative client to access the contents of a forwarding queue for a remote Broker at runtime. In this mode, the forwarding queue is locked for the lifetime of the queue browser. You can browse queue contents, delete documents from queue, insert new documents into the queue, and modify documents in the queue.

To invoke a queue browser operation on the forwarding queue, the Broker administrative client must first create a forwarding queue browser using the BrokerAdminClient.createForwardQueueBrowser() method.

To invoke a queue browser operation on the forwarding queue, the Broker administrative client must first create a forwarding queue browser using one of the following methods:

BrokerAdminClient.createForwardQueueBrowser()

Broker administrative client creates a queue browser to browse forwarding queue.

BrokerAdminClient.createLockedForwardQueueBrowser()

Broker administrative client creates a queue browser to manipulate the contents of a forwarding queue.

This method will return a queue browser that you use to invoke various queue management functions on the queue.

Note: Brokers earlier than version 8.1 do not support the queue browser APIs.


11 Queue Browser

The BrokerQueueBrowserInfo object represents information of a queue browser with data members described in the following table.

BrokerAdminClient

The BrokerAdminClient class is used to represent a Broker administrative client. For more information about the BrokerAdminClient class, see Chapter 4, “Managing Broker Clients”.

You use the createClientQueueBrowser and createLockedClientQueueBrowser methods in the BrokerAdminClient class to create queue browsers on a specific client in unlocked and locked modes, respectively.

You use the createForwardQueueBrowser method to create a queue browser on a specific forward queue for a remote Broker in unlocked mode and createLockedForwardQueueBrowser method in locked mode.

BrokerClient

The BrokerClient class is used to represent a Broker client. For more information about the BrokerClient class, see Chapter 4, “Managing Broker Clients”.

You use the createClientQueueBrowser method in BrokerClient to create a queue browser on the client's own queue. Once you create a queue browser from a client session, that session will be marked as a queue browsing session and cannot be used to retrieve documents from the queue using regular document retrieval methods. Hence, wherever possible, you must create a queue browser on a separate client session.

Note: You cannot use the BrokerClient class to create a queue browser on the forwarding queue for a remote Broker; use the BrokerAdminClient class instead.


String clientId This member contains the ID of the client or remote Broker on which the queue browser is currently open.

String browserId This member contains the ID of the client that created the queue browser. For information on client IDs, see “Queue Browser” on page 139.


This member contains the session ID of the client that created the queue browser.

boolean locked The value is set to true if the client queue is locked by this queue browser; otherwise, false.

int createTime This member contains the date and time when the queue browser was created.


11 Queue Browser

BrokerQueueBrowser and BrokerClientQueueBrowser

Note: BrokerQueueBrowser is an interface for queue browser methods, implementations of which allow you to browse both client queue and forwarding queue. BrokerQueueBrowser interface has two implementations, BrokerClientQueueBrowser for browsing client queues and BrokerForwardQueueBrowser for forwarding queues.

You use the BrokerQueueBrowser interface to access all the methods that you can use to browse a queue.

An application can use the BrokerQueueBrowser interface to perform the following functions on the client queue:

Browse documents in the client's queue.

Selectively browse documents using filters.

An application can use the BrokerQueueBrowser interface to perform the following functions on the forwarding queue for the remote Broker:

Browse documents in the forwarding queue for the remote Broker queue.

Selectively browse documents using filters.

All methods throw BrokerQueueBrowserException (and other exceptions) when necessary.

The BrokerQueueBrowser interface methods are listed in the following table.

Method Description

getBrowserInfo Get browser information of the current queue browser.

setPosition Set the browse cursor to the specified position in the queue.

Note: While setting the position of the browse cursor in a forwarding queue, keep in mind that the queue might also contain Broker internal events. For more information, see “Forwarding Queue Browser” on page 142.

setFilter Set up a single filter for queue browse operations. If the queue browser already has one or more filters, this new filter is added to the list. If a filter is already present for a document type, the existing filter will be overwritten with the new filter. When one or more filters are set on the queue browser, a browse operation only returns documents matching those filters. Note that queue browser filters are applicable only to the browse operation and not to other queue browser operations, such as insert or delete operations.


11 Queue Browser

BrokerLockedQueueBrowser and BrokerLockedClientQueueBrowser

Note: BrokerLockedQueueBrowser is the interface for queue browser methods, implementations of which allow you to browse both client queue and forwarding queue. BrokerLockedQueueBrowser interface has two implementations, BrokerLockedClientQueueBrowser for browsing client queues and BrokerLockedForwardQueueBrowser for forwarding queues.

BrokerLockedQueueBrowser extends the BrokerQueueBrowser interface. In addition to browsing the queue, the BrokerLockedQueueBrowser interface allows you to manipulate the contents of the queue.

setFilters Set up a multiple filters for queue browse operations. If the queue browser already has one or more filters, the new filters are added to the list. If a filter is already present for a document type, the existing filter will be overwritten with the new filter. When filters are set on the queue browser, a browse operation only returns documents matching those filters. Note that queue browser filters are applicable only to the browse operation and not to other queue browser operations, such as insert or delete operations.

resetFilters Reset the filter list on the current queue browser. The filter list on the queue browser will be emptied out.

getFilters Get filters that are currently set for queue browse operation. The existing filters are returned in the form of BrokerFilterDescriptor objects.

browseEvents Read one or more documents from the queue on which the queue browser is opened. This method simply returns documents from the current queue position. The number of documents being returned is not guaranteed to be the requested number of documents, even if the queue contains more than that many documents. Any number of documents up to the value of max_events may be returned.

Note: While returning the documents, the queue browser skips all the internal events that might be queued in a forwarding queue. For more information, see “Forwarding Queue Browser” on page 142.

closeQueueBrowser Close the queue browser and release the associated resources.

Method Description


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.


The additional methods that are available only on BrokerLockedQueueBrowser are listed in the following table. For more information, see BrokerLockedQueueBrowser on page 385.


Creating and Closing Client Queue Browsers

Use the following methods to create and close client queue browsers in each mode.

For a Client Queue Browser

Create a queue browser using the BrokerClient.createClientQueueBrowser() method. This method creates a queue browser on the client's queue.

Note: This mode of operation does not require a client queue to be locked; therefore the client queue content can undergo changes while the queue browser is open.

Close the queue browser using the BrokerClientQueueBrowser.closeClientQueueBrowser() method.

Method Description

modifyEvents Modify documents in the queue. The documents are identified by the specified receipt sequence numbers for an in-place replacement in the queue.

deleteEvents Delete documents in the queue. The documents are identified by the receipt sequence numbers.

insertEventsAtHead Insert documents into the queue at head position.

insertEventsAtTail Insert documents into the queue at tail position.


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.


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


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;


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.


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


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.


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.


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.


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:


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


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.


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.


11 Queue Browser

3 Use browseEvents to view the content of the queue. See “BrokerQueueBrowser and BrokerClientQueueBrowser” on page 146 for instructions.

The following example illustrates how to examine one's own queue content:

BrokerClient client = null; BrokerAdminClient admin = null; BrokerQueueBrowser browser = null; BrokerEvent[] events = null; int max_events = 100;//Maximum number of documents to be browsed int msecs = 30000; //Timeout for the browse operation //Create a Broker client try { client = new BrokerClient(broker_host, broker_name, client_id, client_group, "QueueBrowser - SELF", null); } catch(BrokerException ex) { System.out.println("Failed to create client."); return; } . . . //Create a queue browser try { browser = client.createClientQueueBrowser(); } catch(BrokerException ex) { System.out.println("Failed to create client queue browser."); return; } . . . //Browse operation try { events = browser.browseEvents( max_events, msecs); } catch(BrokerException ex) { System.out.println("Failed to complete browse operation."); return; } . . . //Various browse operations . . . //Close the queue browser try { browser.closeQueueBrowser(); } catch(BrokerException ex) { System.out.println("Failed to close queue browser."); return; }

Administratively Viewing Contents of an Unlocked Client Queue

For an administrative client to examine client queue content in an unlocked mode, follow these steps.


11 Queue Browser

1 Create a queue browser in an unlocked mode using the BrokerAdminClient.createClientQueueBrowser(String client_id) method. This will create a queue browser on the specified client's queue.


2 Set a filter or filters, if needed. It is important to note that once a filter is set for the queue browser, all browse operations will consider only documents that pass the filters. See “Filters on a Queue Browser” on page 154 for instructions.

3 Use browseEvents to view the content of the queue. See “BrokerLockedQueueBrowser and BrokerLockedClientQueueBrowser” on page 147 for instructions.

The following example illustrates how to examine a client queue in unlocked mode:

BrokerClient client = null; BrokerAdminClient admin = null; BrokerQueueBrowser browser = null; BrokerEvent[] events = null; int max_events = 100;//Maximum number of documents to be browsed int msecs = 30000; //Timeout for the browse operation //Create a Broker client try { client = new BrokerClient(broker_host, broker_name, client_id, client_group, "QueueBrowser ", null); } catch(BrokerException ex) { System.out.println("Failed to create client."); return; } //Create a Broker admin client try { admin = new BrokerAdminClient(broker_host, broker_name, null, "admin", "QueueBrowser-UNLOCKED", null); } catch(BrokerException ex) { System.out.println("Failed to create admin client."); return; } . . . //Create a queue browser in unlocked mode try { browser = admin.createClientQueueBrowser(client.getId()); } catch(BrokerException ex) { System.out.println("Failed to create client queue browser."); return; } . . .


11 Queue Browser

//Browse operation try { events = browser.browseEvents(max_events, msecs); } catch(BrokerException ex) { System.out.println("Failed to complete browse operation."); return; } . . . //Various browse operations . . . //Close the queue browser try { browser.closeQueueBrowser(); } catch(BrokerException ex) { System.out.println("Failed to close queue browser."); return; }

Administratively Viewing Contents of a Locked Client Queue

For an administrative client to create a queue browser and examine client queue content in a locked mode, follow these steps.

1 Create a queue browser in locked mode using the BrokerAdminClient.createLockedClientQueueBrowser(String client_id) method. This will acquire a client queue lock to prevent further changes to the client queue. Note that even though the target client queue is locked, the Broker will continue to queue incoming documents according to the client's subscription. “Acquiring a Queue Lock” on page 153 for instructions.

2 Set a filter or filters, if needed. It is important to note that once a filter is set for the queue browser, all browse operations will consider only documents that pass the filters. See “Filters on a Queue Browser” on page 154 for instructions.


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


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.


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.



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


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.



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 {


11 Queue Browser

events = browser.browseEvents(max_events, msecs); } catch(BrokerException ex) { System.out.println("Failed to complete browse operation."); return; } . . . //Various browse operations . . . //Close the queue browser try { browser.closeQueueBrowser(); } catch(BrokerException ex) { System.out.println("Failed to close locked queue browser."); return; }

Identifying "Unacknowledged" Documents

A queue browse operation may return documents including those that are retrieved but not yet acknowledged. These documents are "unacknowledged" or "unacked" documents. The document acknowledgment status information can be retrieved from the returned BrokerEvent object using the following methods.

Use the BrokerEvent.getRetrievedStatus() method to check whether the document is an unacknowledged or not. If the document is unacked, this method returns "true".

If the document is unacked, use the BrokerEvent.getRetrievedSessionId() method to get information on the client session that retrieved this document.

For more information about BrokerEvent, see the webMethods Broker Client Java API Programmer’s Guide.

The following example illustrates how to examine an "unack" status on documents returned from a browse operation:

BrokerAdminClient admin = null; BrokerLockedQueueBrowser browser = null; //Create a Broker admin client try { admin = new BrokerAdminClient(broker_host, broker_name, null, "admin", "QueueBrowser", null); } catch(BrokerException ex) { System.out.println("Failed to create admin client."); return; } . . . //Create a queue browser .... . . . //Browse operation


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


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


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


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


11 Queue Browser

} browser.deleteEvents( seqn); } catch(BrokerException ex) { System.out.println("Failed to complete delete operation."); return; } . . . //Various browse operations . . . //Close the queue browser try { browser.closeQueueBrowser(); } catch(BrokerException ex) { System.out.println("Failed to close client queue browser."); return; }

Unblocking the Forwarding Queue in a Territory or Cluster

If you observe that an internal event in the forwarding queue for a remote Broker is blocking the queue and not allowing events to flow across, you must delete and recreate the remote Broker. If the Broker belongs to a territory or cluster, force the Broker to leave and then rejoin the territory or cluster.

When an internal event is blocking the forwarding queue, do the following to unblock the queue.

To unblock the forwarding queue in a territory or cluster

Note: While changing a territory configuration or cluster configuration, allow some time for metadata changes to completely propagate across the network.

1 Create a backup of all the regular events contained in all the forwarding queues by saving the events to an external file. For more information about viewing events, see “Viewing Queue Content” on page 158, and Administering webMethods Broker.

2 Make the Broker leave the territory, or cluster. For more information, see “Removing a Broker from a Territory” on page 95.

3 Rejoin the Broker to the territory, or cluster. For more information, see “Adding a Broker to an Existing Territory” on page 95.

4 Restore all the regular events to their respective forwarding queues. For more information, see “Inserting Documents” on page 168.


11 Queue Browser

Unblocking the Forwarding Queue in a Territory Gateway or Cluster Gateway

If you observe that an internal event in the forwarding queue for a remote Broker is blocking the queue and not allowing events to flow across, you must delete and recreate the remote Broker. If the Broker belongs to a territory gateway or cluster gateway, delete and recreate the blocked-half of the gateway.

To unblock the forwarding queue in a territory gateway or cluster gateway

Note: While changing a territory gateway configuration or cluster gateway configuration, allow some time for metadata changes to completely propagate across the network.

1 Create a backup of all the regular events contained in all the forwarding queues by saving the events to an external file. For more information about viewing events, see “Viewing Queue Content” on page 158 and Administering webMethods Broker.

2 Save the gateway configuration. For more information about importing and exporting Broker metadata, see Administering webMethods Broker.

3 Delete the blocked-half of the gateway. For more information, see “Creating and Destroying Gateways” on page 98, and “Creating and Destroying Cluster Gateways” on page 109.

4 Reconfigure the gateway. For more information about importing and exporting Broker metadata, see Administering webMethods Broker.

5 Restore all the regular events to their respective forwarding queues. For more information, see “Inserting Documents” on page 168.

Note: Because a Broker in a territory or cluster can have multiple forwarding queues, the backup of the forwarding queue events must be restored (reinserted) in the correct forwarding queue.


11 Queue Browser


12 Java API Administration Reference

AccessControlList . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 175

BrokerAdminClient . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 180

BrokerAdminTypeDef . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 302

BrokerAuthInfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 315

BrokerChangeLockInfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 317

BrokerClientGroupInfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 318

BrokerClientInfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 320

BrokerClientQueueBrowser . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 323

BrokerClientQueueBrowserInfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 326

BrokerClientSession . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 327

BrokerClusterGatewayInfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 331

BrokerClusterInfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 333

BrokerCompleteBroker . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 334

BrokerCompleteClient . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 340

BrokerCompleteClientGroup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 345

BrokerCompleteCollection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 350

BrokerCompleteEventType . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 354

BrokerCompleteServer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 358

BrokerCompleteTerritory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 366

BrokerCompleteTerritoryGateway . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 369

BrokerFilterDescriptor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 374

BrokerForwardQueueBrowser . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 375

BrokerInfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 378

BrokerJoinFailureInfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 379

BrokerLockedClientQueueBrowser . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 380

BrokerLockedForwardQueueBrowser . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 383

BrokerLockedQueueBrowser . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 385

BrokerLogConfig . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 387



BrokerLogConfigEntry . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 394

BrokerMonitorClient . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 395

BrokerProcessInfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 401

BrokerQueueBrowser . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 402

BrokerQueueBrowserInfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 405

BrokerServerClient . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 406

BrokerServerConnectionCallback . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 438

BrokerServerLogEntry . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 439

BrokerServerLogInfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 440

BrokerSetFailureInfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 440

BrokerSharedEventTypeInfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 441

BrokerSharedEventTypeRefuseUpdateInfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 443

BrokerSSLCertificate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 444

BrokerSSLConfig . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 446

BrokerSSLConfigV2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 447

BrokerSSLIdentity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 451

BrokerSSLStatus . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 452

BrokerTerritoryGatewayInfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 453

BrokerTerritoryInfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 456

BrokerTraceEvent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 457



AccessControlList

class BrokerAccessControlList extends java.lang.Object

This class represents a list of distinguished names of trusted entities. It is used by Broker to represent the entities that are allowed administrative access. It is also used by client groups to represent the entities that may create or reconnect a Broker client that is associated with the client group.

The access list is actually composed of two lists. One list contains the distinguished names of entities who are allowed access. The other list contains the distinguished names of certificate issuers who are trusted.

Constructors

BrokerAccessControlList

BrokerAccessControlList()

Creates an empty access control list.

BrokerAccessControlList

BrokerAccessControlList( BrokerAccessControlList acl) throws BrokerException

This is a copy constructor.

Methods

getAuthNames

String[] getAuthNames()

Returns an array of strings containing the names of all certificate authenticators and allowed basic authentication aliases defined in this list.

getAuthNameState

boolean getAuthNameState String name) throws BrokerException

acl The access list to be copied.

Possible Exceptions Meaning

BrokerNullParameterException The acl parameter is null.



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

See Also:

BrokerAccessControlList.setAuthNameState and BrokerAccessControlList.setAuthNameStates

getUserNames

String[] getUserNames()

Returns an array of strings containing all SSL and basic authentication user names in this list.

See Also:

BrokerAccessControlList.getUserNameState and BrokerAccessControlList.setUserNames

getUserNameState

boolean getUserNameState( String name) throws BrokerException

Returns true if the specified name is currently in the list.

See Also:

BrokerAccessControlList.setUserNameState and BrokerAccessControlList.setUserNameStates

setAuthNames

void setAuthNames( String names[]) throws BrokerException

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


BrokerNullParameterException The name parameter is null.

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





Sets the list of names that are certificate authenticators or basic authentication aliases. Certificates issued by any of the listed SSL authenticators will be considered to be trusted.

See Also:

BrokerAccessControlList.getAuthNames and BrokerAccessControlList.setAuthNameState

setAuthNameState

void setAuthNameState( String name, Boolean is_allowed) throws BrokerException

If is_allowed is true and the name is not in this list, it will be added. If is_allowed is false and the name is found in this list, it is removed.

See Also:

BrokerAccessControlList.getAuthNameState and BrokerAccessControlList.setAuthNameStates

setAuthNameStates

void setUserNames( String names[]) throws BrokerException

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


BrokerInvalidNameException One or more of the names in the names array is invalid.

BrokerNullParameterException The names parameter is null or any of its entries is null.

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

name The authenticator or basic authentication alias name to be set for this list.

is_allowed Determines whether the authorizer or basic authentication alias name is added or removed from the list.



BrokerBlankParameterException The name parameter is blank.



If is_allowed is true and any of the names are not in this list, they will be added. If is_allowed is false, any of the names found in this list are removed.

See Also:

BrokerAccessControlList.getAuthNameState and BrokerAccessControlList.setAuthNameState

setUserNames

void setUserNames( String names[]) throws BrokerException

Sets the SSL and basic authentication user names for this list. All previously existing SSL and basic authentication user names in the list are replaced.

See Also:

BrokerAccessControlList.getUserNameState and BrokerAccessControlList.setUserNameState

setUserNameState

void setUserNameState( String name, Boolean is_allowed) throws BrokerException

name The authenticator or basic authentication alias name to be set for this list.

is_allowed Determines whether the authenticator or basic authentication alias names are to be added or removed from the list.


BrokerNullParameterException The names parameter is null or an entry it contains is null.


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


BrokerNullParameterException The names parameter is null or any of its entries is null.




If is_allowed is true and the name is not in this list, it will be added. If is_allowed is false and the name is found in this list, it will be removed.

See Also:

BrokerAccessControlList.getUserNames, BrokerAccessControlList.getUserNameState, BrokerAccessControlList.setUserNameState, and BrokerAccessControlList.setUserNameStates

setUserNameStates

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

If is_allowed is true and any of the names are not in this list, they will be added. If is_allowed is false, any of the names found in this list are removed.

See Also:

BrokerAccessControlList.getUserNameState, BrokerAccessControlList.setUserNames, and BrokerAccessControlList.setUserNameState.

toString

String toString()

name The SSL or basic authentication user name to be set for this list.

is_allowed Determines whether the SSL or basic authentication user name is to be added or removed from the list.




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

is_allowed Determines whether the SSL and basic authentication user names are to be added or removed from the list.


BrokerNullParameterException The names parameter is null or an entry it contains is null.




Returns a string containing the BrokerAccessControlList information in a human-readable format.

toString

String toString( int indent_level, String name)

Converts the access control list contained in this object into a string format that may be saved to a file.

BrokerAdminClient

class BrokerAdminClient extends COM.activesw.aweb.client.BrokerClient

This class represents a connection between an administrative client application and a Broker. This class provides methods for obtaining and setting the various administrative features of Brokers, Broker clients, and client groups.

The BrokerAdminClient class extends the BrokerClient class, described in the webMethods Broker Client Java API Programmer’s Guide, and therefore it has access to all of the BrokerClient methods.

Constants

LIFECYCLE_DESTROY_ON_DISCONNECT

LIFECYCLE_EXPLICIT_DESTROY

AUTH_TYPE_NONE

AUTH_TYPE_SSL

Constructor

BrokerAdminClient

BrokerAdminClient( String broker_host, String broker_name, String client_id, String client_group,

indent_level The number of 4-character spaces to use for indentation.

name An optional name for the access list. Can be set to null.



String app_name, BrokerConnectionDescriptor desc) throws BrokerException

Creates a BrokerAdminClient object that is identical to a BrokerClient, except that it may use all of the special administration methods. The client is created with an empty event queue and no event subscriptions.

The application is responsible for invoking either the BrokerClient.disconnect or BrokerClient.destroy method, described in the webMethods Broker Client Java API Programmer’s Guide, when the BrokerAdminClient is no longer needed.

broker_host The name of the host where the Broker is running that the new Broker client will use. Specified in the form <broker_host_name>:<port_number>. If you omit the port number, the default port number will be used. For example: MyHost:12000.

broker_name The name of the Broker to which the new Broker client will be connected. If null, the default Broker will be used.

client_id A string containing a unique identifier for the new Broker client to be used when disconnecting or reconnecting. If null, the Broker will generate a unique client identifier. A null value is usually supplied for Broker clients whose life cycle is destroy-on-disconnect. See the webMethods Broker Client Java API Programmer’s Guide for more information on client identifiers.

client_group The name of the client group for the new Broker client. Client groups are discussed in Administering webMethods Broker.

app_name The name of the application that will contain the new Broker client.

desc The connection descriptor to use for the new Broker client. If null, a default connection will be established for the new Broker client, which may be shared with other Broker clients.


BrokerClientExistsException Another Broker client is already using the specified client_id.

BrokerClientQueueBrowserException An operation pertaining to the creation or access of a client queue browser failed. This exception wraps all queue browser related errors into a single exception for convenience, with the minor codes on the exception detailing the specifics of the failure. This exception is thrown for errors on both client and administrative queue browser.



See Also:

BrokerClient.disconnect, BrokerClient.destroy, BrokerAdminClient.newOrReconnectAdmin, and BrokerAdminClient.reconnectAdmin.

Methods

abort Methods

abortForced

void abortForced(long tx_id) throws BrokerException;

Forcibly terminates a transaction.

BrokerQueueBrowserException An operation pertaining to the creation or access of a client queue or forwarding queue browser failed. This exception wraps all queue browser-related errors into a single exception for convenience, with the minor codes on the exception detailing the specifics of the failure. This exception is thrown for errors on both client and administrative queue browser.

BrokerCommFailureException A problem occurred establishing the connection.

BrokerHostNotFoundException The specified broker_host does not exist.

BrokerInvalidClientIdException The client_id contains invalid characters.

BrokerNoPermissionException Permission to join the client_group was denied.

BrokerNotRunningException A Broker could not be found on the broker_host.

BrokerNullParameterException The broker_host, client_group, or app_name parameter is null.

BrokerUnknownBrokerNameException The specified broker_name does not exist. If broker_name was null, then there is no default Broker.

BrokerUnknownClientGroupException The specified client_group does not exist on the Broker.

tx_id The Broker transaction context to abort.




abortForced

void abortForced(long tx_ids[]) throws BrokerException;

Forcibly terminates a list of transactions.

acquire Method

acquireChangeLock

BrokerChangeLockInfo acquireChangeLock() throws BrokerException

Returns a BrokerChangeLockInfo object for the Broker to which this client is connected. The use of this method allows cooperating client applications to avoid race conditions when updating the same Broker.

If a different client has already acquired a lock to this client's Broker, the acquired variable will be set to 0 (false) and the client_id, session_id will be set to the client and session holding the lock. The lock_time variable will contain the date and time when the lock was acquired.

If your client successfully acquires a lock on its Broker, the acquired variables will be set to 1 (true), client_id and lock_time will be set to null, and session_id will be set to zero.

It is safe to call this method again after acquiring the lock.

Exception Description

BrokerInvalidClientException The client has been destroyed or disconnected

BrokerInvalidTxException The transaction does not exist or the transaction state does not allow it to be aborted.

BrokerNoPermissionException The client does not have sufficient permissions.

tx_id A list of Broker transaction contexts to abort.


BrokerInvalidClientException The client has been destroyed or disconnected

BrokerNullParameterException tx_ids is null.

BrokerInvalidTxException One or more transactions do not exist or the transaction state does not allow it to be aborted.

BrokerNoPermissionException The BrokerAdminClient does not have necessary permissions on the Broker.



See Also:

BrokerAdminClient.releaseChangeLock

add Method

addBrokerToCluster

BrokerJoinFailureInfo addBrokerToCluster( String broker_host, String broker_name) throws BrokerException

Causes this client's Broker join the cluster of the Broker with the specified broker_name that is running on broker_host. If the join operation is successful, a null value is returned. Otherwise, a BrokerJoinFailureInfo object will be returned that describes the client groups and event types defined for this Broker that conflict with the cluster's definitions.

For more information on the concept of clusters, see Administering webMethods Broker.


BrokerIncompatibleVersionException The Broker Server does not support this operation.

BrokerInvalidClientException The BrokerAdminClient has been destroyed or disconnected.

broker_host The Broker host where broker_name is located. Specified in the form <broker_host_name>:<port_number>. If you omit the port number, the default port number will be used. For example: MyHost:12000.

broker_name The name of the Broker whose cluster this Broker must join. This parameter may not be null.



BrokerInClusterException This client's Broker is already a member of a cluster.


BrokerNoPermissionException The BrokerAdminClient does not have permission to modify the Broker's properties or the Broker is not licensed for Broker interconnection.

BrokerNotInClusterException The Broker specified by broker_name is not a member of a cluster.



See Also:

BrokerAdminClient.createCluster, BrokerAdminClient.getBrokersInCluster, BrokerAdminClient.getClusterStats, BrokerAdminClient.leaveCluster, and BrokerAdminClient.removeBrokerFromCluster

check Methods

checkAndRestartForwarding

int checkAndRestartForwarding() throws BrokerException

Checks for inactivity and restarts forwarding documents on remote Brokers, where remote Brokers include territory and gateway Brokers. If the reconnection request was successful, the non-zero return value indicates the actual number of remote Broker connections that were restarted. If the reconnection request was unsuccessful or no reconnection was necessary, the return value is a zero.

checkAndRestartForwarding

int checkAndRestartForwarding(String remote_broker_name) throws BrokerException

Checks for inactivity and restarts forwarding documents for a specific remote Broker. This remote Broker can be a territory or gateway Broker. If the reconnection request to the specified Broker was successful, the return value is one. If the reconnection request to the specified Broker was unsuccessful or no reconnection was necessary, the return value is a zero.

BrokerNullParameterException The parameter broker_host or broker_name is null.

BrokerOutOfRangeException There is another Broker in the specified cluster with the same name.

BrokerSecurityException If the cluster requires SSL and the joining Broker does not support SSL.

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

BrokerSSLClusterException SSL connection error between Broker Servers.


BrokerInvalidClientException The BrokerAdminClient is invalid.

BrokerNullParameterException The remote Broker name is null.

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




clear Method

clearClientQueueById

void clearQueue( String client_id) throws BrokerException

Clears all events in the queue for the client with the specified client_id.

You can obtain a list of client identifiers by invoking the one of the following methods:

getClientIds

getClientIdsByClientGroup

getClientIdsWhichAreSubscribed

Important! Use this method with care because it deletes events that have not yet been processed by the Broker client(s) using the queue.

See Also:

BrokerAdminClient.getClientStatsById

commit Methods

commitForced

void commitForced(long tx_id) throws BrokerException


BrokerInvalidClientException The BrokerAdminClient is invalid.

BrokerNullParameterException The specified remote Broker name is null.

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



BrokerNoPermissionException Permission to delete the client's events was denied.

BrokerNullParameterException The client_id parameter is null.

BrokerUnknownClientIdException The specified client does not exist on the Broker.



Forcibly commits a transaction.

commitForced

void commitForced( long tx_ids[]) throws BrokerException

Forcibly commits a list of transactions.

create Methods

createClient

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

tx_id The Broker transaction context to commit.



BrokerInvalidTxException Transaction tx_id does not exist or the transaction state does not allow it to be committed.


tx_ids A list of Broker transaction contexts to commit.



BrokerInvalidTxException One or more transactions do not exist or the transaction state does not allow it to be committed.


client_id The client identifier. See the webMethods Broker Client Java API Programmer’s Guide for more information on client identifiers.



Creates a new Broker client on the Broker to which this administrative client is connected. Since this method does not result in a connection being opened with the Broker for the newly created client, the Broker client's groups must have a life cycle of explicit-destroy.

If either user_name or authenticator_name is null, the client is created without an owner.

The only property of the BrokerConnectionDescriptor desc that affects this method is the shared state setting.

Note: For information on client group name and client identifier restrictions, see the webMethods Broker Client Java API Programmer’s Guide.

createClientGroup

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



desc The connection descriptor used to set state sharing for the client. If set to null, state sharing will be disabled.

user_name The user name of the entity creating the client.

authenticator_name The name of the authenticator that issued the certificate for user_name.


BrokerClientExistsException Another Broker client is already using the specified client_id.



BrokerInvalidNameException The app_name parameter contains invalid characters.

BrokerNoPermissionException The client does not have permission to modify clients in the specified client group.

BrokerNullParameterException The client_id, client_group_name, or app_name parameter is null.

BrokerUnknownClientGroupException The specified client_group does not exist.



Creates a new client group on the Broker, setting the life cycle and the storage type for the clients associated with the group.

Note: Once a client group has been created, the life cycle and storage type cannot be changed.

The types of event to which clients can subscribe, the events they may publish, and the group's access control list must all be set separately.

See Also:

BrokerAdminClient.getClientGroupNames, BrokerAdminClient.setClientGroupCanPublishList, BrokerAdminClient.setClientGroupCanSubscribeList, BrokerAdminClient.setClientGroupDescription, and BrokerAdminClient.setClientInfosetById

createClientQueueBrowser

BrokerClientQueueBrowser createClientQueueBrowser(String client_id) throws BrokerException

client_group_name The name of the client group to be created. See the webMethods Broker Client Java API Programmer’s Guide for details on group name restrictions.

life_cycle The life cycle of the clients associated with the group. Must be either LIFECYCLE_DESTROY_ON_DISCONNECT or LIFECYCLE_EXPLICIT_DESTROY.

storage_type The storage type of the event queue for clients associated with the group. Must be one of these values:

BrokerTypeDef.STORAGE_GUARANTEED

BrokerTypeDef.STORAGE_VOLATILE


BrokerClientGroupExistsException A client group with the specified name already exists on the Broker.


BrokerInvalidClientGroupNameException The specified client group name is not valid.

BrokerNoPermissionException The client does not have permission create a client group.

BrokerNullParameterException The client_group_name parameter is null.

BrokerOutOfRangeException The life_cycle or storage_parameter parameter contains an invalid value.



Create an administrative client queue browser on the specified client's queue so that the administrative client can browse a client queue without acquiring the client's queue lock. Returns a BrokerClientQueueBrowser object if successful, otherwise throws a BrokerException. See “Queue Browser” on page 139 for more information about queue browsers.

See Also:

BrokerAdminClient.createLockedClientQueueBrowser and BrokerAdminClient.getClientQueueBrowsers

createClientSubscriptionById

void createClientSubscriptionById( String client_id, BrokerSubscription sub) throws BrokerException

Registers a subscription for the Broker client with the specified client_id for all events which match the subscription sub. An exception will be thrown if the BrokerAdminClient does not have permission to modify the client's subscription list or if the Broker client does not have permission to subscribe to the event.

Note: If the subscription has already been registered for the specified Broker client, invoking this method will have no effect.

You can use the doesClientSubscriptionExistById method to test for existing subscriptions.

You can obtain a list of client identifiers by invoking any of the following methods:

getClientIds




BrokerIncompatibleVersionException An attempt was made to create a queue browser on a pre-6.5 Broker client, which does not support queue browsers.

BrokerInvalidClientException The client has been already destroyed.

BrokerUnknownClientIdException The specified client ID does not exist on the Broker.

BrokerClientQueueBrowserException A client queue browser is already open on the client queue from the same session.

client_id The identifier of the Broker client for which the subscription is to be created.

sub The subscription to register for the Broker client, which specifies an event type name and a filter.



See Also:

BrokerAdminClient.createClientSubscriptionsById, BrokerAdminClient.destroyClientSubscriptionById, BrokerAdminClient.destroyClientSubscriptionsById, BrokerAdminClient.doesClientSubscriptionExistById, and BrokerAdminClient.getClientSubscriptionsById

createClientSubscriptionsById

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

Registers multiple subscriptions for the Broker client with the specified client_id. An exception will be thrown if the calling BrokerAdminClient does not have permission to modify the client's subscription list or if the Broker client does not have permission to subscribe to any of the events.

Note: Any subscription specified in subs that is invalid or has already been registered for the specified Broker client will be ignored. Invalid subscriptions will cause an exception to be thrown. In both cases, all valid subscriptions will still be registered.

You can use the doesClientSubscriptionExistById method to test for existing subscriptions.


getClientIds



BrokerInvalidSubscriptionException The filter string in sub contains a parse error.

BrokerNoPermissionException The BrokerAdminClient does not have permission to modify the Broker client's subscription list or the Broker client is not allowed to subscribe to the event type.

BrokerNullParameterException The client_id, sub, or sub.event_type_name parameter is null.


BrokerUnknownEventTypeException The event type does not exist on the Broker.

client_id The identifier of the Broker client for which the subscription is to be created.

subs The array of subscriptions to register for the Broker client, with each element specifying an event type name and a filter.





See Also:

BrokerAdminClient.createClientSubscriptionById, BrokerAdminClient.destroyClientSubscriptionById, BrokerAdminClient.destroyClientSubscriptionsById, BrokerAdminClient.doesClientSubscriptionExistById, and BrokerAdminClient.getClientSubscriptionsById

createCluster

void createCluster( String cluster_name) throws BrokerException

Creates a new cluster with this Broker as the first member in the cluster. No warning will be issued if a cluster already exists with the same name. For more information on the concept of clusters, see Administering webMethods Broker.



BrokerInvalidSubscriptionException One or more of the filter strings in subs contains a parse error. All correctly formatted subscriptions are still registered.

BrokerNoPermissionException The BrokerAdminClient does not have permission to modify the Broker client's subscription list or the Broker client is not allowed to subscribe to at least one of the event types specified in subs.

BrokerNullParameterException The parameter client_id, subs, a member of the subs array, or the event_type_name within a subscription is null.

BrokerOutOfRangeException One of the elements in subs has a sub_id that is less that zero.

BrokerUnknownClientIdException The specified client does not exist on Broker.


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


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



See Also:

BrokerAdminClient.createClusterGateway, BrokerAdminClient.getBrokersInCluster, BrokerAdminClient.getClusterStats, BrokerAdminClient.addBrokerToCluster, BrokerAdminClient.leaveCluster, BrokerAdminClient.removeBrokerFromCluster, BrokerAdminClient.setClientGroupACL, and BrokerAdminClient.setEventTypesAndClientGroups

createClusterGateway

void createClusterGateway( String cluster_name, String broker_host, String broker_name, boolean isPrimary) throws BrokerException

Creates a cluster gateway to the specified cluster by having the current Broker communicate with the Broker specified by broker_host and broker_name. This will only create one half of the gateway.

In order to complete the cluster gateway, this method must be invoked on the other Broker that makes up the gateway. Until both Brokers have created their halves of the gateway, the gateway will remain in an incomplete state.


BrokerInvalidClusterNameException The cluster name specified is not valid.


BrokerNullParameterException The cluster_name parameter is null.

cluster_name The name of the cluster to which this gateway is being created.

broker_host The name of the remote host that is running the Broker which will act as the other end of the cluster gateway. Specified in the form <broker_host_name>:<port_number>. If you omit the port number, the default port number will be used. For example: MyHost:12000.

broker_name The name of the remote Broker that will act as the other end of the cluster gateway.

isPrimary The cluster gateway connection will be made primary if set to true.






See Also:

BrokerAdminClient.createCluster and BrokerAdminClient.destroyClusterGateway.

createForwardQueueBrowser

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

Create an administrative forwarding queue browser on the forwarding queue of the specified remote Broker so that the administrative client can browse the forwarding queue without acquiring the remote Broker's queue lock. Returns a BrokerQueueBrowser object if successful, otherwise throws a BrokerException. See “Queue Browser” on page 139 for more information about queue browsers.



BrokerNotInClusterException The Broker is not a member of a cluster.

BrokerNotRunningException A Broker Server could not be found on the broker_host.

BrokerNullParameterException The cluster_name, broker_host, or broker_name is null.

BrokerOutOfRangeException The cluster_name is already connected to the cluster of broker_host through some other gateway, or a primary gateway already exists to the specified cluster.

BrokerUnknownBrokerNameException If the specified Broker does not exist.

BrokerUnknownClusterException There is no gateway to the specified cluster from this Broker.

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


BrokerInvalidClientException The forwarding queue has been already destroyed or is disconnected.

BrokerUnknownClientIdException The forwarding queue for the remote Broker specified does not exist on Broker.




createLockedClientQueueBrowser

BrokerLockedClientQueueBrowser createClientQueueBrowser(String client_id) throws BrokerException

Create an administrative client queue browser on the specified client's queue in locked mode. In the locked browse mode the client queue is locked for the lifetime of the queue browser. Using this queue browser, you can browse queue contents, delete documents from queue, insert new documents in to the queue and modify (in-place update) documents in the queue. Returns a BrokerClientQueueBrowser object if successful, otherwise throws a BrokerException. See “Queue Browser” on page 139 for more information about queue browsers.

See Also:

BrokerAdminClient.createClientQueueBrowser and BrokerAdminClient.getClientQueueBrowsers

createLockedForwardQueueBrowser

BrokerLockedForwardQueueBrowser createForwardQueueBrowser(String remoteBroker) throws BrokerException

Create an administrative forward queue browser on the specified forwarding queue in locked mode. In the locked browse mode the forwarding queue is locked for the lifetime of the queue browser. Returns a BrokerLockedQueueBrowser object if successful, otherwise throws a BrokerException. See “Queue Browser” on page 139 for more information about queue browsers.


BrokerIncompatibleVersionException An attempt was made to create a queue browser on a pre-6.5 Broker client, which does not support queue browsers.


BrokerUnknownClientIdException The specified client ID does not exist on the Broker.

BrokerClientQueueBrowserException A client queue browser is already open on the client queue from the same session.


BrokerIncompatibleVersionException An attempt was made to create a queue browser on a pre-8.1 Broker Server, which does not support forwarding queue browsers.

BrokerInvalidClientException The client has been already destroyed or is disconnected.



See Also:

BrokerAdminClient.createForwardQueueBrowser.

createTerritory

void createTerritory( String territory_name) throws BrokerException

Creates a new territory with this Broker as the first member in the territory. No warning will be issued if a territory already exists which has the same name. For more information on the concept of territories, see Administering webMethods Broker.

See Also:

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

BrokerQueueBrowserException The forwarding queue for the remote Broker specified does not exist on Broker.

BrokerQueueBrowserException A queue browser is already open on the forwarding queue from the same session.

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


BrokerInTerritoryException The Broker is already a member of the specified territory.


BrokerInvalidTerritoryNameException The territory name specified is not valid.


BrokerNullParameterException The parameter territory_name is null.

BrokerSecurityException If the territory requires SSL and the joining Broker does not support SSL.




createTerritoryGateway

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

Creates a gateway to the specified territory by having the current Broker communicate with the Broker specified by broker_host and broker_name. This will only create one half of the gateway.

In order to complete the gateway, this method must be invoked on the other Broker that makes up the gateway. Until both Brokers have created their halves of the gateway, the gateway will remain in an incomplete state.

See Also:

BrokerAdminClient.createTerritory and BrokerAdminClient.destroyTerritoryGateway

territory_name The name of the territory to which this gateway is being created.

broker_host The name of the remote host that is running the Broker which will act as the other end of the gateway. Specified in the form <broker_host_name>:<port_number>. If you omit the port number, the default port number will be used. For example: MyHost:12000.

broker_name The name of the remote Broker that will act as the other end of the gateway.





BrokerNotInTerritoryException The Broker is not a member of a territory.


BrokerNullParameterException The territory_name, broker_host, or broker_name is null.

BrokerOutOfRangeException The territory_name is already connected to the territory of broker_host through some other gateway.

BrokerUnknownTerritoryException There is no gateway to the specified territory from this Broker.



delete Method

deleteLogEvents

int deleteLogEvents( int from_index, int num_events) throws BrokerException

Deletes one or more events from the Broker's log. The number of events being deleted is not guaranteed to be 'n_events'. Returns the number of events deleted.

In addition, any of the communications errors can occur.

destroy Methods

destroyBroker

void destroyBroker() throws BrokerException

Destroys the Broker to which this BrokerAdminClient is currently connected.

See Also:

BrokerServerClient.destroy

from_index events to be deleted starting from this index

num_events number of events to be deleted



BrokerNullParameterException Events are null.

BrokerOutOfRangeException Index is less than zero.


BrokerInTerritoryException The Broker is in a territory with at least one other Broker and must leave the territory before being destroyed.

BrokerInvalidClientException The BrokerServerClient has been destroyed or disconnected.

BrokerNoPermissionException Client does not have permission to destroy the Broker.



destroyClientById

void destroyClientById( String client_id) throws BrokerException

Destroys the BrokerClient with the specified client_id, including the event queue, the list of subscriptions, and all other state allocated for the client in the Broker.


getClientIds



See Also:

BrokerAdminClient.BrokerAdminClient, BrokerAdminClient.disconnectClientById, BrokerAdminClient.disconnectClientSessionById, BrokerClient.destroy, and BrokerClient.disconnect

destroyClientGroup

void destroyClientGroup( String client_group_name, boolean reserved1) throws BrokerException

Destroys the specified client group. If any existing Broker clients belong to the group, a BrokerDependencyException exception will be thrown and the client group will not be destroyed.

You can use the getClientIdsByClientGroup method to obtain a list of any Broker clients currently belonging to a group.

client_id The identifier of the Broker client to be destroyed.



BrokerNoPermissionException The BrokerAdminClient does not have permission to destroy the specified Broker client.

BrokerNullParameterException The parameter client_id is null.


client_group_name The name of the client group to be destroyed.

reserved1 Reserved for future. Must be set to false.



See Also:

BrokerAdminClient.createClientGroup, BrokerAdminClient.getClientGroupNames, and BrokerAdminClient.getClientIdsByClientGroup

destroyClientSubscriptionById

void destroyClientSubscriptionById( String client_id, BrokerSubscription sub) throws BrokerException

Cancels the subscription with the matching event type and filter for the Broker client with the specified client_id. Only the event type name and filter, specified by sub, are used to match the subscription.


getClientIds




BrokerDependencyException One or more Broker clients are members of the client group.


BrokerNoPermissionException The BrokerAdminClient does not have permission to destroy the client group.

BrokerNullParameterException The parameter client_group_name is null.

BrokerUnknownClientGroupException The specified client group does not exist on the Broker.

client_id The identifier of the Broker client for which the subscription is to be cancelled.

sub The subscription to be cancelled for the Broker client, which specifies an event type name and a filter. The filter field may be null and the sub_id field is ignored.



BrokerInvalidSubscriptionException There is no matching subscription for the specified Broker client.



See Also:

BrokerAdminClient.createClientSubscriptionById, BrokerAdminClient.createClientSubscriptionsById, BrokerAdminClient.destroyClientSubscriptionsById, BrokerAdminClient.doesClientSubscriptionExistById, and BrokerAdminClient.getClientSubscriptionsById

destroyClientSubscriptionsById

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

Cancels multiple subscription for the Broker client with the specified client_id. Only the event type name and filter, specified in each element of the subs array, are used to match each subscription.


getClientIds



BrokerNoPermissionException The BrokerAdminClient does not have permission to modify the Broker client's subscription list.

BrokerNullParameterException The client_id, sub, or sub.event_type_name parameter is null.


client_id The identifier of the Broker client whose subscription are to be cancelled.

subs The array of subscriptions to be cancelled for the Broker client, with each element specifying an event type name and a filter. An element's filter field may be null and its sub_id field is ignored.






See Also:

BrokerAdminClient.createClientSubscriptionById, BrokerAdminClient.createClientSubscriptionsById, BrokerAdminClient.destroyClientSubscriptionById, BrokerAdminClient.doesClientSubscriptionExistById, and BrokerAdminClient.getClientSubscriptionsById

destroyClusterGateway

void destroyClusterGateway( String cluster_name, String broker_name) throws BrokerException

Destroys one half of the gateway to the specified cluster.

This method will only destroy one half of the gateway. To completely remove the gateway, this method must be invoked on the other Broker that make up the gateway. Until that is done, the gateway on the other Broker will be in an incomplete state.

BrokerInvalidSubscriptionException There are no matching subscriptions for the specified Broker client for one or more of the specified subscriptions. If this exception is thrown, all matching subscriptions will still be destroyed.

BrokerNoPermissionException The BrokerAdminClient does not have permission to modify the Broker client's subscription list.

BrokerNullParameterException The client_id or subs, parameter is null, any element in subs is null, or any element's event_type_name field is null.


cluster_name The name of the cluster whose gateway is to be destroyed.

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



BrokerNoPermissionException The BrokerAdminClient does not have permission to modify the Broker's properties.





See Also:

BrokerAdminClient.createCluster and BrokerAdminClient.createClusterGateway

destroyEventType

void destroyEventType( String event_type_name, boolean reserved1) throws BrokerException

Destroys the specified event type. If an existing Broker client subscription or client group uses the event type, a BrokerDependencyException exception will be thrown and the event type will not be destroyed.



getClientGroupsWhichCanPublish

getClientGroupsWhichCanSubscribe

BrokerNullParameterException The cluster_name or broker_name parameter value is null.

BrokerUnknownClusterException There is no gateway connection to the specified cluster from this Broker.

event_type_name The name of the event type to be destroyed.

reserved1 Reserved for future. Must be set to false.


BrokerDependencyException One or more client groups have can-publish or can-subscribe permission to the event type or the event type is specified in one or more Broker client subscriptions.


BrokerNoPermissionException The BrokerAdminClient does not have permission to destroy the event type.

BrokerNullParameterException The parameter event_type_name is null.





See Also:

BrokerAdminClient.destroyEventTypes, BrokerAdminClient.getEventAdminTypeDef, BrokerAdminClient.getEventAdminTypeDefs, BrokerAdminClient.setEventAdminTypeDef, and BrokerAdminClient.setEventAdminTypeDefs

destroyEventTypeInfoset

void destroyEventTypeInfoset( String event_type_name, String infoset_name) throws BrokerException

Destroys the specified infoset for the specified event type.

See Also:

BrokerAdminClient.destroyEventTypeInfosets, BrokerAdminClient.setEventTypeInfoset, BrokerAdminClient.setEventTypeInfosets as well as BrokerClient.getEventTypeInfoset, and BrokerClient.getEventTypeInfosets (described in the webMethods Broker Client Java API Programmer’s Guide)

destroyEventTypeInfosets

void destroyEventTypeInfosets( String event_type_name, String infoset_names[]) throws BrokerException

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

infoset_name The name of the infoset to be destroyed.



BrokerNoPermissionException The BrokerAdminClient does not have permission to destroy the event type infoset.

BrokerNullParameterException The parameter event_type_name or infoset_name is null.


BrokerUnknownInfosetException The infoset does not exist on the Broker.

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

infoset_names The names of the infosets to be destroyed.



Destroys the specified infosets for the specified event type. If infoset_names is null, all infosets for the specified event type will be destroyed.

Note: If an infoset contained in infoset_names cannot be found. it will be ignored.

See Also:

BrokerAdminClient.destroyEventTypeInfosets, BrokerAdminClient.setEventTypeInfoset, BrokerAdminClient.setEventTypeInfosets, BrokerClient.getEventTypeInfoset, and BrokerClient.getEventTypeInfosets

destroyEventTypes

void destroyEventTypes( String event_type_names[], boolean force_destroy) throws BrokerException

Destroys the specified event types. The force_destroy flag determines whether or not any currently existing Broker client subscription or client group that uses any of the event types will be affected.

Note: If an event type name contained in event_type_names cannot be found, it will be ignored.






BrokerNoPermissionException The BrokerAdminClient does not have permission to destroy the event type infoset.

BrokerNullParameterException The parameter event_type_name or any entry in infoset_names is null.


event_type_names An array of names of the event types to be destroyed.

force_destroy If set to true, any Broker client subscriptions using any of the event types are destroyed as are any can-publish or can-subscribe entries in any client groups. If set to false, an exception is raised if at least one event type is used in any subscription or client group.




See Also:

BrokerAdminClient.destroyEventTypeInfosets, BrokerAdminClient.setEventTypeInfoset, BrokerAdminClient.setEventTypeInfosets, BrokerClient.getEventTypeInfoset, and BrokerClient.getEventTypeInfosets

destroyTerritoryGateway

void destroyTerritoryGateway( String territory_name) throws BrokerException

Destroys one half of the gateway to the specified territory.

This method will only destroy one half of the gateway. It must be invoked on each of the two Brokers that make up the gateway. Until that is done, the gateway on the other Broker will be in an incomplete state.the gateway will remain in an incomplete state.


BrokerDependencyException The parameter force_destroy is false and any of the event_type_names is used by one or more Broker client subscriptions or by one or more client groups. If this exception is thrown, no event types will be destroyed.


BrokerNoPermissionException The BrokerAdminClient does not have permission to destroy the event types.

BrokerNullParameterException The parameter event_type_names is null or any of its elements is null.

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





BrokerNullParameterException The territory_name parameter is null.




See Also:

BrokerAdminClient.createTerritory and BrokerAdminClient.createTerritoryGateway

disconnect Methods

disconnectClientById

void disconnectClientById( String client_id) throws BrokerException

Closes all sessions for the specified Broker client. The effect of this method depends on the life cycle of the Broker client, which is defined by the client group to which it belongs. Client groups are described in Administering webMethods Broker.

If the Broker client's life cycle is destroy-on-disconnect, the client state associated this BrokerClient is destroyed when it is disconnected. When the state is destroyed, any queued events and subscriptions are destroyed.

If the Broker client's life cycle is explicit-destroy, the Broker client's state on the Broker will persist until the Broker client is explicitly destroyed with the destroy method. In this case, calling the method BrokerClient.disconnect simply breaks the Broker client's connection to the Broker. After the Broker client is disconnected:

The associated client state continues to exist.

The Broker continues to queue messages for the Broker client.

The Broker client can resume processing events by reconnecting to the Broker.


getClientIds



See Also:

BrokerAdminClient.destroyClientById and BrokerAdminClient.disconnectClientSessionById

client_id The identifier of the Broker client to be disconnected.



BrokerNoPermissionException The BrokerAdminClient does not have permission to disconnect the Broker client.

BrokerNullParameterException The parameter client_id is null.




disconnectClientSessionById

void disconnectClientSessionById( String client_id, int session_id) throws BrokerException

Disconnects the specified session for the Broker client. The effect of this method depends on the life cycle of the Broker client, which is defined by the client group to which it belongs. Client groups are described in Administering webMethods Broker.


getClientIds



You can obtain a list of session identifiers how using one of the following methods:

getClientInfoById

getClientInfosById

See Also:

BrokerAdminClient.destroyClientById

does Method

doesClientSubscriptionExistById

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

client_id The identifier of the Broker client.

session_id The identifier of the session to be disconnected.



BrokerNoPermissionException The BrokerAdminClient does not have permission to disconnect the Broker client.



BrokerUnknownSessionIdException The specified client session does not exist on the Broker.



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.


getClientIds



See Also:

BrokerAdminClient.createClientSubscriptionById, BrokerAdminClient.createClientSubscriptionsById, BrokerAdminClient.destroyClientSubscriptionById, BrokerAdminClient.destroyClientSubscriptionsById, BrokerAdminClient.getClientGroupsWhichCanSubscribe, BrokerAdminClient.getClientIdsWhichAreSubscribed, and BrokerAdminClient.getClientSubscriptionsById

forget Methods

forgetForced

void forgetForced(long tx_id) throws BrokerException;

Forcibly purge a heuristic transaction.

client_id The identifier of the Broker client whose subscription is being tested.

event_type_name The event type name associated with the subscription being tested.

filter The filter associated with the subscription being tested. This parameter can be set to null.



BrokerNoPermissionException The BrokerAdminClient does not have permission to read the Broker client's subscriptions.

BrokerNullParameterException The client_id or event_type_name parameter is null.


tx_id The Broker transaction context to purge.



forgetForced

void forgetForced(long tx_ids[]) throws BrokerException;

Forcibly purge a list of heuristic transactions.

forgetForced

void forgetForced() throws BrokerException;

Forcibly purge all heuristic transactions.

get Methods

getActivityTraces

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



BrokerInvalidTxException The transaction does not exist.


tx_ids A list of Broker transaction contexts to purge.



BrokerNullParameterException tx_ids is null.







Returns an array of BrokerTraceEvent objects containing Broker activity traces. The first element contains a number that should be used to set seqn plus one for all subsequent calls.

Important! Only the last 100 activity traces are available through this method, so you should not rely on this method to provide complete trace information. If the Broker is exceptionally busy or if this method is called infrequently, trace information will be lost.

getAllClusterGateways

BrokerClusterGatewayInfo[] getAllClusterGateways() throws BrokerException

Returns all of the cluster gateways accessible from this Broker, through local gateways or gateways from other Brokers.

getAllQueueStats

public BrokerAllQueueStat[] getAllQueueStats() throws BrokerException

Returns a BrokerEvent object containing statistics for all clients.

seqn The index of the activity trace array to be returned. This should be set to 0 on the first invocation. For all subsequent invocations it should be set to one plus the value of the sequence number of the last element returned on the previous invocation.

msecs The number of milliseconds this method will wait for trace information to be returned. If set to -1, it will block indefinitely.


BrokerInterruptedException This operation was interrupted before it could be completed.


BrokerNoPermissionException The BrokerAdminClient does not have permission to read the activity traces.



BrokerNoPermissionException The BrokerAdminClient does not have permission to browse the Broker.




The event returned by the BrokerAdminClient.getAllQueueStats method contains fields described in the following table.


now BrokerDate Current time on the Broker host.

createTime BrokerDate Time when the client was created.

numEventsPublished int Number of events published by this client.

numEventsForwarded int Number of events forwarded by the forwarding queue for the remote Broker.

numEventsDelivered int Number of events delivered by this client.

numEventsReceived int Number of events received by the forwarding queue for the remote Broker.

numEventsQueued int Number of events queued for this client.

numEventsEnqueued int Number of events enqueued for the forwarding queue.

numEventsRetrieved int Number of events retrieved by this client.

lastEventPublishTime BrokerDate Time when last event was published by this client. A date and time value of zero indicates that the client has never published an event.

lastEventForwardTime BrokerDate Time when last event was forwarded by the forwarding queue. A date and time value of zero indicates that the forwarding queue has never forwarded an event.

lastEventDeliveryTime BrokerDate Time when last event was delivered by this client. A date and time value of zero indicates that the client has never delivered an event.

lastEventReceiveTime BrokerDate Time when last event was received by this forward queue. A date and time value of zero indicates that the forward queue has never received an event.

lastEventQueueTime BrokerDate Time when last event was queued for this client. A date and time value of zero indicates that the client has never queued an event.

lastEventRetrieveTime BrokerDate Time when last event was retrieved by this client. A date and time value of zero indicates that the client has never retrieved an event.



getAllTerritoryGateways

BrokerTerritoryGatewayInfo[] getAllTerritoryGateways() throws BrokerException

Returns all of the territory gateways accessible from this Broker, through local gateways or gateways from other Brokers.

getBrokerDescription

String getBrokerDescription() throws BrokerException

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

lastConnectTime BrokerDate Time when last session connected.

lastConnectSession int Session ID of the last connected session.

lastDisconnectTime BrokerDate Time when last session disconnected.

lastDisconnectSession int Session ID of the last disconnected session.

queueLength long Number of events in client queue.

queueByteSize long Number of bytes worth of events in client queue.

queueHighestLength long Highest value of queueLength.

queueHighestLengthTime BrokerDate Time when queueHighestLength was last set. A date and time value of zero indicates that the queueHighestLength has never been set.












See Also:

BrokerAdminClient.setBrokerDescription

getBrokersInCluster

BrokerInfo[] getBrokersInCluster() throws BrokerException

Returns an array of BrokerInfo objects, one for each Broker in this Broker's cluster. This Broker will appear first in the list.

See Also:

BrokerAdminClient.createCluster, BrokerAdminClient.getClusterStats, BrokerAdminClient.addBrokerToCluster, BrokerAdminClient.leaveCluster, and BrokerAdminClient.removeBrokerFromCluster

getBrokersInTerritory

BrokerInfo[] getBrokersInTerritory() throws BrokerException

Returns an array of BrokerInfo objects, one for each Broker in this Broker's territory. This Broker will appear first in the list.





BrokerNoPermissionException The BrokerAdminClient does not have permission to read the Broker's properties.

BrokerNotInClusterException This Broker is not part of a cluster.



BrokerNoPermissionException The BrokerAdminClient does not have permission to read the Broker's properties.

BrokerNotInTerritoryException This Broker is not part of a territory.



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.


createTime BrokerDate The time the Broker was created.

eventLogLength long The number of events in the Broker log.


numClients int The number of clients on the Broker, including disconnected clients.

numEventTypes int The number of event types installed.

numEventsDelivered int The number of events delivered by all clients.

numEventPublished int The number of events published by all clients.

numEventsQueued int The number of events placed in client queues.

numTracesPublished int The number of trace events published by Broker.

retryQueueMaxPublishes int The maximum number of publishes.

retryQueueMaxEvents int The maximum number of events.

retryQueueNextOpsSequenceNum int Next operation sequence number.

retryQueueReservedGuaranteedEvents int The number of guaranteed events.



See Also:

BrokerAdminClient.getClientGroupStats, BrokerAdminClient.getClientStatsById, and BrokerAdminClient.getEventTypeStats

retryQueueReservedGuaranteedPublishes int The number of guaranteed publishes.

retryQueueReservedTotalPublishes int The total number of reserved publishes.

retryQueueReservedVolatileEvents int The number of volatile events.

retryQueueReservedVolatilePublishes int The number of volatile publishes.

retryQueueCurrentEvents int The number of current events.

retryQueueCurrentPublishes int The number of current publishes.

traceLastEventEnqueueTime date The time when last event was enqueued.

traceNumEventsQueued int The number of events placed in the queue.

traceQueueByteSize long The number of bytes worth of events in the queue.

traceQueueHighestLength long The highest value of traceQueueLength.

traceQueueHighestLengthTime date The time when traceQueueHighestLength was last set. Forever (zero date and time) if an event was never queued.

traceQueueLength long The number of events in queue.



BrokerNoPermissionException The BrokerAdminClient does not have permission to read the Broker's statistics.




getClientGroupACL

BrokerAccessControlList getClientGroupACL( String client_group_name) throws BrokerException

Returns an array of strings containing the distinguished names of entities that may create and use Broker clients that belong to the specified client group.

See AccessControlList for more information on the format of the returned object.

See Also:

BrokerAdminClient.setClientGroupACL

getClientGroupCanPublishList

String[] getClientGroupCanPublishList( String client_group_name) throws BrokerException

Returns an array of strings containing the event types that may be published or delivered by Broker clients that belong to the specified client group.

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



BrokerNoPermissionException The BrokerAdminClient does not have permission to read the client group's Access Control List.


BrokerUnknownClientGroupException The specified client_group_name does not exist on the Broker.

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



BrokerNoPermissionException The BrokerAdminClient does not have permission to read the client group's can-publish list.





See Also:

BrokerAdminClient.getClientGroupCanSubscribeList, BrokerAdminClient.setClientGroupCanPublishList, and BrokerAdminClient.setClientGroupCanSubscribeList

getClientGroupCanSubscribeList

String[] getClientGroupCanSubscribeList( String client_group_name) throws BrokerException

Returns an array of strings containing the event types that may be subscribed to, or which may be delivered to, Broker clients that belong to the specified client group.

See Also:

BrokerAdminClient.getClientGroupCanPublishList, BrokerAdminClient.setClientGroupCanPublishList, and BrokerAdminClient.setClientGroupCanSubscribeList

getClientGroupInfo

BrokerClientGroupInfo getClientGroupInfo( String client_group_name) throws BrokerException

Returns the client group's information.

See BrokerClientGroupInfo for more information on the format of the returned object.

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



BrokerNoPermissionException The BrokerAdminClient does not have permission to read the client group's can-subscribe list.



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





See Also:

BrokerAdminClient.getClientGroupInfos and BrokerAdminClient.getClientGroupNames

getClientGroupInfos

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

Returns an array of BrokerClientGroupInfo objects containing the client groups' information. A null entry will be returned for each client group names you specify which could not be found or which your client does not have permission to browse.

See Also:

BrokerAdminClient.getClientGroupInfo, BrokerAdminClient.getClientGroupNames

getClientGroupLogAcknowledgeList

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

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

BrokerNoPermissionException The BrokerAdminClient does not have permission to read the client group's information.



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



BrokerNullParameterException An entry in the client_group_names parameter is null.

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




getClientGroupLogPublishList

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

Get the list of event types that are logged when published or delivered by a client in the specified client group.

getClientGroupNames

String[] getClientGroupNames() throws BrokerException

Returns an array of strings containing the names of all the client groups known to the Broker which your client has permission to browse.

See Also:

BrokerAdminClient.getClientGroupInfo and BrokerAdminClient.getClientGroupInfos



BrokerNoPermissionException The BrokerAdminClient does not have permission to browse the client group's information.






BrokerNoPermissionException The BrokerAdminClient does not have permission to browse the client group's information.







getClientGroupStats

BrokerEvent getClientGroupStats( String client_group_name) throws BrokerException

Returns a BrokerEvent object containing statistics for the specified client group.

The following table shows the events returned by the BrokerAdminClient.getClientGroupStats method.

See Also:

BrokerAdminClient.getBrokerStats, BrokerAdminClient.getClientStatsById, and BrokerAdminClient.getEventTypeStats


String[] getClientGroupsWhichCanPublish( String event_type_name) throws BrokerException

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



createTime BrokerDate The time the client group was created.

numEventsDelivered int The number of events delivered by all clients in this group.

numEventsPublished int The number of events published by all clients in this group.

lastEventDeliveryTime BrokerDate Time when an event was last delivered by a client in this group.

lastEventPublishTime BrokerDate Time when an event was last published by a client in this group.

lastUpdateTime BrokerDate Time when this group was last updated.



BrokerNoPermissionException The BrokerAdminClient does not have permission to get the client group's statistics.





Returns an array of strings containing the names of the client groups which can publish the specified event type. Only those client groups which your client has permission to browse will be returned. Clients may always browse their own client group.

Note: A zero length array will be returned if your client does not have permission to read the Broker's properties.

See Also:

BrokerAdminClient.getClientGroupsWhichCanPublish and BrokerAdminClient.setClientGroupCanPublishList


String[] getClientGroupsWhichCanSubscribe( String event_type_name) throws BrokerException

Returns an array of strings containing the names of the client groups which can subscribe to or receive a delivered event with the specified event type. Only those client groups which your client has permission to browse will be returned. Clients may always browse their own client group.

Note: A zero length array will be returned if your client does not have permission to read the Broker's properties.

event_type_name The name of the event type.



BrokerNullParameterException The event_type_name parameter is null.

BrokerUnknownEventTypeException The specified event_type_name does not exist on the Broker.








See Also:

BrokerAdminClient.getClientGroupCanSubscribeList and BrokerAdminClient.setClientGroupCanSubscribeList

getClientIds

String[] getClientIds() throws BrokerException

Returns an array of strings containing the identifiers of all the clients on the Broker which your client has permission to browse.

See Also:

BrokerAdminClient.getClientIdsByClientGroup and BrokerAdminClient.getClientIdsWhichAreSubscribed


String[] getClientIdsByClientGroup( String client_group_name) throws BrokerException

Returns an array of strings containing the client identifiers of all Broker clients belonging to the specified client group which your client has permission to browse.

See Also:

BrokerAdminClient.getClientIds and BrokerAdminClient.getClientIdsWhichAreSubscribed



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



BrokerNoPermissionException The BrokerAdminClient does not have permission to get the list of client identifiers.






String[] getClientIdsWhichAreSubscribed( String event_type_name) throws BrokerException

Returns an array of strings containing the identifiers of the clients which have registered subscriptions for the specified event type. Only the identifiers for those client which your client has permission to browse will be returned.

See Also:

BrokerAdminClient.getClientIds and BrokerAdminClient.getClientIdsByClientGroup

getClientInfoById

BrokerClientInfo getClientInfoById( String client_id) throws BrokerException

Returns a BrokerClientInfo object containing information on the specified Broker client.


getClientIds








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



BrokerNoPermissionException The BrokerAdminClient does not have permission to get the client information.


BrokerUnknownClientIdException The specified client_id does not exist on the Broker.



See Also:

BrokerAdminClient.getClientInfosById

getClientInfosById

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

Returns an array of BrokerClientInfo objects containing information on the specified Broker clients. The array returned will be the same size as the client_ids array. The returned array may have null entries if:

The client identifier does not exist on the Broker.

This BrokerAdminClient does not have permission to read the Broker's properties.


getClientIds



See Also:

BrokerAdminClient.getClientInfoById

getClientInfosetById

BrokerEvent getClientInfosetById( String client_id) throws BrokerException

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

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



BrokerNullParameterException An entry in the client_ids array is null.

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



See Also:

BrokerAdminClient.setClientInfosetById

getClientQueueBrowsers

BrokerClientQueueBrowser[] getClientQueueBrowser(String client_id) throws BrokerException

Get information on the queue browsers that are opened by the specified client. Returns an array of BrokerClientQueueBrowser objects whose length corresponds to the number of active queue browsers on the specified client queue. Each of the BrokerClientQueueBrowser object holds details of the active queue browsers.

See Also:

BrokerAdminClient.createClientQueueBrowser and BrokerAdminClient.createLockedClientQueueBrowser

getClientQueueLock

Note: Support for the queue manipulation feature is dropped and replaced by the queue browser feature in webMethods Broker Java API version 6.5.

BrokerClientQueueLock getClientQueueLock( java.lang.String client_id) throws BrokerException



BrokerNoPermissionException The BrokerAdminClient does not have permission to get the client infoset.




BrokerIncompatibleVersionException

An attempt was made to create a queue browser on a pre-6.5 Broker client, which does not support queue browsers.


client_id Represents the id of the client whose queue will be locked.

flags (0) Not yet implemented. Returns BrokerClientQueueLock object.



Use this method to lock the client queue. This method is used for queue manipulation. Returns a BrokerClientQueueLock object from which you can perform various operations on the client queue.

getClientStatsById

BrokerEvent getClientStatsById( String client_id) throws BrokerException

Returns BrokerEvent containing statistics for the specified Broker client.

The following table shows the events returned by the BrokerAdminClient.getClientStatsById method.

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



createTime BrokerDate The time the client was created.

numEventsDelivered int The number of events delivered by the client.

numEventsPublished int The number of events published by the client.

numEventsRetrieved int The number of events retrieved by the client.

lastEventDeliveryTime BrokerDate Time when an event was last delivered by a client in this group. A value of zero means no event has ever been delivered.

lastEventPublishTime BrokerDate Time when an event was last published by a client in this group. A value of zero means no event has ever been published.

lastEventQueueTime BrokerDate Time when an event was last placed in this client's queue. A value of zero means no event has ever been queued.

lastEventRetrieveTime BrokerDate Time when an event was last retrieved from the queue by a client. A value of zero means no event has ever been retrieved.

queueLength long Number of events in the client's queue.

queueByteSize long The number of bytes of events in the client's queue.

queueHighestLength long Highest value of queue length, so far.




getClientIds



See Also:

BrokerAdminClient.getBrokerStats, BrokerAdminClient.getClientGroupStats, and BrokerAdminClient.getEventTypeStats

getClientSubscriptionsById

BrokerSubscription[] getClientSubscriptionsById( String client_id) throws BrokerException

Returns an array of BrokerSubscription objects containing the event subscriptions that have been registered for the specified Broker client.


getClientIds



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



BrokerNoPermissionException The BrokerAdminClient does not have permission to get the client's statistics.



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




See Also:

BrokerAdminClient.createClientSubscriptionById, BrokerAdminClient.createClientSubscriptionsById, BrokerAdminClient.destroyClientSubscriptionsById, BrokerAdminClient.destroyClientSubscriptionById, and BrokerAdminClient.doesClientSubscriptionExistById

getClusterACL

BrokerAccessControlList getClusterACL() throws BrokerException

Returns the access control list which the Brokers in the cluster are using to accept connections from other Brokers in remote cluster.

If access control is not being performed, the list will have zero entries. The list will have one entry if access control is enabled.

See Also:

BrokerAdminClient.setClusterACL

getClusterGatewayACL

BrokerAccessControlList getClusterGatewayACL( String cluster_name) throws BrokerException

Returns the access control list (ACL) this Broker uses to authenticate the connections with the remote Brokers that makes up the other half of the gateway.



BrokerNoPermissionException The BrokerAdminClient does not have permission to get the client's subscription list.







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




See Also:

BrokerAdminClient.setClusterGatewayACL.

getClusterGatewayKeepAlive

int getClusterGatewayKeepAlive( String cluster_name) throws BrokerException

This method returns the gateway Broker's keep-alive interval for the cluster specified in cluster_name. The keep-alive interval specifies the number of seconds of idle time after which the gateway Broker issues a keep-alive message to the cluster specified in cluster_name. A return value of 0 indicates that the keep-alive feature is disabled.

See also BrokerAdminClient.setClusterGatewayKeepAlive.





BrokerNullParameterException The cluster_name parameter value is null.

BrokerUnknownClusterException There is no gateway to the specified cluster from this client's Broker.

cluster_name The name of the cluster whose keep-alive status you want to check.





BrokerNullParameterException The cluster_name parameter value is null.




getClusterGatewayRefuseAllUpdates

boolean getClusterGatewayRefuseAllUpdates( String cluster_name) throws BrokerException

Returns whether a cluster gateway refuses all the updates made in a connected cluster (true) or accepts all the updates (false).

See Also:

BrokerAdminClient.setClusterGatewayRefuseAllUpdates.

getClusterGatewaySharedEventTypes

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

Gets the complete list of event types shared across a cluster gateway.

See BrokerSharedEventTypeInfo for more information.

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





BrokerNullParameterException The cluster_name parameter is null.


cluster_name The name of the cluster whose event types are shared.

broker_name The name of the Broker in the specified cluster. This Broker is used to identify the right gateway link for information retrieval.


BrokerInvalidClientException The BrokerAdminClient has been destroyed or disconnected

BrokerNoPermissionException The client does not have permission to modify the Broker.



See Also:

BrokerAdminClient.setClusterGatewaySharedEventTypes.

getClusterGatewayStats

BrokerEvent getClusterGatewayStats( String cluster_name, String broker_name) throws BrokerException

Returns a BrokerEvent containing statistics for the gateway for the specified cluster. For more information on the concept of cluster, see Administering webMethods Broker.

The following table shows the events returned by the BrokerAdminClient.getClusterGatewayStats method.

BrokerNotInClusterException If the specified Broker is not a member of the specified cluster.

BrokerNullParameterException The cluster_name or broker_name parameter value is null.

BrokerUnknownClusterException There is no gateway connection to the specified cluster from this Broker.

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

broker_name The name of the Broker in the specified cluster. This Broker is used to identify the right gateway link for information retrieval.


authProtocol unicode_string The protocol being used to authenticate the Broker. Only set if connectedFrom is not empty and authentication is used. Currently, the only supported value is "SSL".

authVersion unicode_string The version of the authentication protocol being used to authenticate the Broker. Only set if authProtocol is not empty. Currently supported values are "2" and "3".

connectedFrom unicode_string The IP address of the remote Broker. Set to an empty string if the gateway is not connected.




encryptLevel unicode_string The level of encryption being used. Only set if encryptProtocol is set. Currently supported values are "USDomestic" and "USExport".

encryptProtocol unicode_string The encryption protocol being used. Only set if connectedFrom is not empty. The only values currently supported is "SSL".

encryptVersion unicode_string The version of the encryption protocol being used. Only set if encryptProtocol is not empty. Currently supported values are "2" and "3".

gateway_pause boolean A flag indicating whether outbound traffic from this gateway Broker to cluster_name is enabled or disabled (paused). Will be true if outbound traffic to cluster_name has been paused. See setClusterGatewayPause.

gateway_pause_client String The client id of the BrokerAdminClient that paused the gateway. If outbound traffic is not currently paused for cluster_name, this parameter will be empty.

gateway_pause_session integer The session id from which the gateway was paused. If outbound traffic is not currently paused for cluster_name, this parameter will be 0.

gateway_pause_time date The time when the gateway was paused. If outbound traffic is not currently paused for cluster_name, this parameter will be 0.

gatewayBrokerName unicode_string The name of the gateway Broker.

gatewayHost unicode_string The name of the gateway Broker's host.

lastConnectTime Date The time the Broker was last connected. Set to zero if never connected.

lastEventEnqueueTime Date Time when an event was last enqueued for the gateway.




lastEventForwardTime Date Time when an event was last forwarded across the gateway. Set to zero if no events have been forwarded.

lastEventReceiveTime Date Time when an event was last received across the gateway. Set to zero if no events have been received.

now Date Current time on the Broker host.

numEventsForwarded int Number of events that were forwarded across the gateway.

numEventsReceived int The number of events received across the gateway.

numEventsEnqueued int Number of events enqueued for the gateway.

queueByteSize int The current size, in bytes, of the gateway's queue.

queueHighestLength int The highest number of events in the gateway's queue.

queueHighestLengthTime BrokerDate Time when queueHighestLength was last changed.

queueLength int The number of events currently in the gateway's queue.

remoteClusterName unicode_string The name of the cluster.

sslCertBeginDate Date The date of the Broker's certificate became valid.

sslCertSerialNumber unicode_string The serial number of the Broker's certificate. Set only if authProtocol is set to "SSL".

sslCertEndDate BrokerDate The date the Broker's certificate expires. Set only if authProtocol is set to "SSL"

sslCertStatus unicode_string The status of the other Broker's certificate. Set only if authProtocol is set to "SSL".

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




See Also:

BrokerAdminClient.addBrokerToCluster

getClusterInfo

BrokerClusterInfo getClusterInfo() throws BrokerException

Returns a BrokerClusterInfo object that contains the cluster settings.

getClusterStaticGatewayForwarding

boolean getClusterStaticGatewayForwarding(String cluster_name) throws BrokerException

This method returns the status of the current static gateway as true if the static gateway forwarding is set on the given remote cluster from the current Broker and false if the static gateway forwarding is not set.

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



BrokerNoPermissionException The BrokerAdminClient does not have permission to get the cluster statistics.

BrokerNotInClusterException This client's Broker is not part of a cluster.

BrokerNullParameterException The cluster_name or broker_name parameter is null.





BrokerNotInClusterException This client's Broker is not a member of a cluster.

cluster_name The name of the remote cluster.




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:


BrokerInvalidClientException The client is not valid.

BrokerNotInClusterException The gateway Broker is not in a cluster.

BrokerUnknownClusterException On the current Broker, there is no local gateway to the specified remote cluster.

BrokerNullParameterException The cluster_name is null.


brokers structure[] The time the event type was created. This includes changes to the definition, the time-to-live setting, or any infoset. A value of zero means there have been no changes since this event type was created

brokers.authProtocol unicode_string The protocol being used to authenticate the Broker. Only set if connectedFrom is not empty and authentication is used. Currently, the only supported value is "SSL".

brokers.authVersion unicode_string The version of the authentication protocol being used to authenticate the Broker. Only set if authProtocol is not empty. Currently supported values are "2" and "3".



brokers.brokerHost unicode_string The Broker host name.

brokers.brokerName unicode_string The Broker Server name.

brokers.connectedFrom boolean Set to true if the Broker is currently connected.

brokers.description unicode_string The Broker's description.

brokers.encryptLevel unicode_string The level of encryption being used. Only set if encryptProtocol is set. Currently supported values are "USDomestic" and "USExport".

brokers.encryptProtocol unicode_string The encryption protocol being used. Only set if connectedFrom is not empty. The only values currently supported is "SSL".

brokers.encryptVersion unicode_string The version of the encryption protocol being used. Only set if encryptProtocol is not empty. Currently supported values are "2" and "3".

brokers.lastConnectTime BrokerDate The time the Broker was last connected. Set to zero if never connected.

brokers.lastEventEnqueueTime BrokerDate The time an event was last enqueued for the Broker. Set to zero if no events have ever be enqueued.

brokers.lastEventForwardTime BrokerDate Time when an event of this type was last forwarded to the Broker. Set to zero if no events have been forwarded.

brokers.lastEventReceiveTime BrokerDate Time when an event was last received by the Broker. Set to zero if no events have been received.

brokers.numEventsEnqueued int Number of events that were enqueued for the Broker.




brokers.numEventsForwarded int Number of events that were forwarded to the Broker.

brokers.numEventsReceived int The number of events received by the Broker.

brokers.queueByteSize int The current size, in bytes, of the Broker's queue.

brokers.queueHighestLength int The highest number of events in the Broker's queue.

brokers.queueHighestLengthTime BrokerDate Time when queueHighestLength was last changed.

brokers.queueLength int The number of events currently in the Broker's queue.

brokers.sslCertBeginDate BrokerDate The date of the Broker's certificate became valid.

brokers.sslCertSerialNumber unicode_string The serial number of the Broker's certificate. Set only if authProtocol is set to "SSL".

brokers.sslCertEndDate BrokerDate The date the Broker's certificate expires.

brokers.sslCertStatus unicode_string The status of the Broker's certificate. Set only if authProtocol is set to "SSL".

brokers.sslDistinguishedName unicode_string The distinguished name s of the Broker's certificate. Set only if authProtocol is set to "SSL".

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


clusterName unicode_string The name of the cluster.




getEventAdminTypeDef

BrokerAdminTypeDef getEventAdminTypeDef( String event_type_name) throws BrokerException

Returns a BrokerAdminTypeDef object containing the type definition for the specified event type.

See Also:

BrokerAdminClient.destroyEventType, BrokerAdminClient.destroyEventTypes, BrokerAdminClient.getEventAdminTypeDef, BrokerAdminClient.getEventAdminTypeDefsByScope, BrokerAdminClient.setEventAdminTypeDef, and BrokerAdminClient.setEventAdminTypeDefs

getEventAdminTypeDefs

BrokerAdminTypeDef[] getEventAdminTypeDefs( String event_type_names[]) throws BrokerException

Returns an array of BrokerAdminTypeDef objects containing the type definitions for the specified event types. If event_type_names is null, this method returns all the event types that this client can browse. Clients may always browse those event types which they can publish or to which they can subscribe.

The array returned will be the same size as the event_type_names array. The returned array may have null entries if:

An event type does not exist on the Broker.

This BrokerAdminClient does not have permission to read the Broker's properties.

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



BrokerNoPermissionException The BrokerAdminClient does not have permission to read the event type definition.



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



Note: Clients always have read permission for the event types which they can publish or to which they may subscribe.

See Also:

BrokerAdminClient.destroyEventType, BrokerAdminClient.destroyEventTypes, BrokerAdminClient.getEventAdminTypeDef, BrokerAdminClient.getEventAdminTypeDefsByScope, BrokerAdminClient.setEventAdminTypeDef, and BrokerAdminClient.setEventAdminTypeDefs

getEventAdminTypeDefsByScope

BrokerAdminTypeDef[] getEventAdminTypeDefsByScope( String scope_name) throws BrokerException

Returns an array of BrokerAdminTypeDef objects containing the event type definitions for the event types in the specified scope.

Note: A zero length array will be returned if your client does not have permission to read any events within the specified scope. Clients always have read permission for the event types which they can publish or to which they may subscribe.

See Also:

BrokerAdminClient.destroyEventType, BrokerAdminClient.destroyEventTypes, BrokerAdminClient.getEventAdminTypeDef, BrokerAdminClient.getEventAdminTypeDefs, BrokerAdminClient.setEventAdminTypeDef, and BrokerAdminClient.setEventAdminTypeDefs



BrokerNullParameterException The event_type_names parameter, or any element in that array is null.

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



BrokerNullParameterException The scope_name parameter is null.

BrokerUnknownEventTypeException The scope does not exist on the Broker.



getEventLogging

boolean getEventLogging() throws BrokerException

This method allows you to get the logging state on the current Broker. If this method returns false(0), logging has been disabled. No events will be logged. If this methods returns true(1), logging has been enabled. Events published and acknowledged will be logged.

getEventTypeStats

BrokerEvent getEventTypeStats( String event_type_name) throws BrokerException

Returns a BrokerEvent containing statistics for the specified event type.

The following table shows events returned by the BrokerAdminClient.getEventTypeStats method:

event_type_name The event type whose statistics are to be returned.


createTime BrokerDate The time the event type was created.

lastEventDeliveryTime BrokerDate Time when an event of this type was last delivered on this Broker.

lastEventPublishTime BrokerDate Time when an event of this type was last published on this Broker.

lastForwardReceivedTime BrokerDate Time when an event of this type was last forwarded to this Broker by another Broker.


numClientSubscriptions int Number of open subscriptions which include this event type by Clients on this Broker.

numEventsDelivered int The number of events of this type that have been delivered on this Broker.

numEventsPublished int The number of events of this type that have been published on this Broker.

numForwardsReceived int Number of events of this type that were forwarded to this Broker by another Broker.

numGroupsCanPublish int Number of client groups that can publish this event type.



See Also:

BrokerAdminClient.getBrokerStats, BrokerAdminClient.getClientGroupStats, and BrokerAdminClient.getClientStatsById

getHeuristicTransactions

BrokerEvent[] getHeuristicTransactions() throws BrokerException;

Returns a BrokerEvent containing the following information for the current heuristic transactions in the Broker transaction manager.

numGroupsCanSubscribe int Number of client groups that can subscribe to this event type.

updateTime BrokerDate The time the event type was last modified. This includes changes to the definition, the time-to-live setting, or any infoset. A value of zero means there have been no changes since this event type was created.



BrokerNoPermissionException The BrokerAdminClient does not have permission to get the event's statistics.


BrokerUnknownEventTypeException The specified event type does not exist on the Broker.

Field Name Type

now BrokerDate

transactions struct[]

transactions.transactionId long

transactions.externalId UnicodeString

transactions.clientId UnicodeString

transactions.sessionId int

transactions.state int

transactions.createdTime BrokerDate




See Also:

BrokerAdminClient.forgetForced

getLocalClusterGateways

BrokerClusterGatewayInfo[] getLocalClusterGateways() throws BrokerException

Returns a list of clusters for which this Broker is acting as a gateway.

See Also:

BrokerAdminClient.getAllClusterGateways

transactions.endedTime BrokerDate

transactions.preparedTime BrokerDate

transactions.closedTime BrokerDate

transactions.closedReason int

transactions.unpreparedTimeout BrokerDate

transactions.preparedTimeoutInterval int

transactions.preparedTimeout BrokerDate

transactions.numEventsReceived int

transactions.numEventsAcknowledged int

transactions.numEventsPublished int








Field Name Type



getLocalTerritoryGateways

BrokerTerritoryGatewayInfo[] getLocalTerritoryGateways() throws BrokerException

Returns a list of territories for which this Broker is acting as a gateway.

See Also:

BrokerAdminClient.getAllTerritoryGateways

getLogEvents

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

Gets one or more events from the Brokers event log at the given zero-based index. The number of events being returned is not guaranteed to be max_events even if there are more than max_events in the client's queue. Any number of events up to the value of max_events may be returned. In addition to the listed exceptions, any communications exception can be thrown. Throws an exception with the following major code setting: INVALID_CLIENT if the client is not valid. NULL_PARAM if n or events are NULL. In addition, any of the communications errors can occur.





from_index Events to be logged starting from this index.

max_events Maximum number of events that may be logged.

msecs



BrokerOutOfRangeException from_index is less than zero.

BrokerNullParameterException max_events, msecs equals zero.

BrokerTimeoutException Reply from Broker is null.

BrokerException XcellpadX



getLogLength

int getLogLength() throws BrokerException

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

getPostPrepareTimeout

int getPostPrepareTimeout() throws BrokerException

Returns the default setting for the post-prepare time-out, in seconds. The post-prepare time-out is the period of time between the point when a transaction is prepared and when it is committed.

See Also:

BrokerAdminClient.setPrePrepareTimeout and BrokerAdminClient.getPostPrepareTimeoutAction

getPostPrepareTimeoutAction

int getPostPrepareTimeoutAction() throws BrokerException

Returns an integer representing the action that the Broker transaction manager will take when a prepared transactions times out (i.e., when the transaction is not committed within the time by the Broker's post-prepare time out period).


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




BrokerIncompatibleVersionException The Broker does not support transaction administration.







See Also:

BrokerAdminClient.setPostPrepareTimeoutAction and BrokerAdminClient.getPostPrepareTimeout

getPrePrepareTimeout

int getPrePrepareTimeout() throws BrokerException

Returns the setting for the pre-prepare time-out, in seconds. The pre-prepare time-out is the period of time between the point when a transaction begins, until it is asked to prepare.

See Also:

BrokerAdminClient.setPrePrepareTimeout

getRecoverMode

int getRecoverMode() throws BrokerException

Returns an integer representing the current recover-mode setting. The recover-mode setting determines whether the Broker transaction manager allows clients to recover any recoverable transaction (RECOVER_GLOBAL) or only those transaction in which they participated (RECOVER_RESTRICTED).

See Also:

BrokerAdminClient.setRecoverMode

getRemoteBrokerKeepAlive

void getRemoteBrokerKeepAlive( String broker_name) throws BrokerException










This method returns the remote Broker's keep-alive interval to the Broker specified in broker_name. The keep-alive interval specifies the number of seconds of idle time after which the remote Broker issues a keep-alive message to the Broker specified in broker_name. A return value of 0 indicates that the keep-alive feature is disabled.

For more information, see “Maintaining a Connection Between Brokers in a Territory” on page 96 and “Maintaining a Connection Between Brokers in a Cluster” on page 108.

See also BrokerAdminClient.setRemoteBrokerKeepAlive

getStaticGatewayForwarding

boolean getStaticGatewayForwarding(String territory_name) throws BrokerException

This method returns the status of the current static gateway as: true if the static gateway forwarding is set on the given remote territory from the current Broker and false if the static gateway forwarding is not set.

See Also:

BrokerAdminClient.setStaticGatewayForwarding

getTerritoryACL

BrokerAccessControlList getTerritoryACL() throws BrokerException

Returns the access control list which Brokers in the territory are using to accept connections from other Brokers in their territory.

broker_name The name of the Broker whose keep-alive status you want to check.



BrokerNullParameterException territory_name is null

territory_name name of the remote territory


BrokerInvalidClientException The client is not valid.

BrokerNotInTerritoryException The gateway Broker is not in a territory.

BrokerUnknownTerritoryException On the current Broker, there is no local gateway to the specified remote territory.

BrokerNullParameterException territory_name is full.




See Also:

BrokerAdminClient.setTerritoryACL

getTerritoryGatewayACL

BrokerAccessControlList getTerritoryGatewayACL( String territory_name) throws BrokerException

Returns the access control list which this Broker is using to authenticate the remote Broker that makes up the other half of the gateway.


See Also:

BrokerAdminClient.setTerritoryGatewayKeepAlive

getTerritoryGatewayKeepAlive

int getTerritoryGatewayKeepAlive( String territory_name) throws BrokerException





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





BrokerUnknownTerritoryException There is no gateway to the specified territory from this client's Broker.



This method returns the gateway Broker's keep-alive interval for the territory specified in territory_name. The keep-alive interval specifies the number of seconds of idle time after which the gateway Broker issues a keep-alive message to the territory specified in territory_name. A return value of 0 indicates that the keep-alive feature is disabled.

See also BrokerAdminClient.setTerritoryGatewayKeepAlive

getTerritoryGatewayRefuseAllUpdates

public boolean getTerritoryGatewayRefuseAllUpdates( String territory_name) throws BrokerException

Returns whether a territory gateway refuses all updates made in a connected territory (true) or accepts all the updates (false).

See Also:

BrokerAdminClient.setTerritoryGatewayRefuseAllUpdates

territory_name The name of the territory whose keep-alive status you want to check.




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









getTerritoryGatewayRefuseEventTypeUpdates

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

Returns information about whether updates for a document type that are made in a connected territory are refused.

See Also:

BrokerAdminClient.setTerritoryGatewayRefuseEventTypeUpdates

getTerritoryGatewaySharedEventTypes

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

Gets the complete list of event types shared across a territory gateway.


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

infos Specifies whether the events and updates for a specified document type are refused.







territory_name The name of the territory whose event types are shared.

infos The shared event type information.





See Also:

BrokerAdminClient.setTerritoryGatewaySharedEventTypes

getTerritoryGatewayStats

BrokerEvent getTerritoryGatewayStats( String territory_name) throws BrokerException

Returns a BrokerEvent containing statistics for the gateway for the specified territory. For more information on the concept of territories, see Administering webMethods Broker.

The following table shows events returned by the BrokerAdminClient.getTerritoryGatewayStats method.

BrokerInvalidSubscriptionException A parse error was encountered in one of the elements contained in infos.

BrokerInvalidTypeDefException One or more of the event types is incompatible with the type definition on the remote Broker.


BrokerNotInTerritoryException The Broker to which this client is connected is not part of a territory.

BrokerNotRunningException The gateway connection is currently not open.

BrokerNullParameterException The territory_name or infos parameter is null, or an element in infos is null, or an element in infos has a nullevent_type_name.

BrokerOutOfRangeException An event type in infos does not have accept_subscribe permission, but has a non-empty subscription_filter.

BrokerUnknownEventTypeException An element in infos does not exist on either Broker in the gateway. If this exception is thrown, no changes are applied.

BrokerUnknownTerritoryException There is no gateway to the specified territory from the local Broker.

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





authProtocol unicode_string The protocol being used to authenticate the Broker. Only set if connectedFrom is not empty and authentication is used. Currently, the only supported value is "SSL".

authVersion unicode_string The version of the authentication protocol being used to authenticate the Broker. Only set if authProtocol is not empty. Currently supported values are "2" and "3".

connectedFrom unicode_string The IP address of the remote Broker. Set to an empty string if the gateway is not connected.

encryptLevel unicode_string The level of encryption being used. Only set if encryptProtocol is set. Currently supported values are "USDomestic" and "USExport".

encryptProtocol unicode_string The encryption protocol being used. Only set if connectedFrom is not empty. The only values currently supported is "SSL".

encryptVersion unicode_string The version of the encryption protocol being used. Only set if encryptProtocol is not empty. Currently supported values are "2" and "3".

gatewayHost unicode_string The name of the gateway Broker's host.

gatewayBrokerName unicode_string The name of the gateway Broker.

lastConnectTime BrokerDate The time the Broker was last connected. Set to zero if never connected.

lastEventEnqueueTime BrokerDate Time when an event was last enqueued for the gateway.

lastEventForwardTime BrokerDate Time when an event was last forwarded across the gateway. Set to zero if no events have been forwarded.



lastEventReceiveTime BrokerDate Time when an event was last received across the gateway. Set to zero if no events have been received.


numEventsForwarded int Number of events that were forwarded across the gateway.

numEventsReceived int The number of events received across the gateway.

numEventsEnqueued int Number of events enqueued for the gateway.

queueByteSize int The current size, in bytes, of the gateway's queue.

queueHighestLength int The highest number of events in the gateway's queue.

queueHighestLengthTime BrokerDate Time when queueHighestLength was last changed.

queueLength int The number of events currently in the gateway's queue.

remoteTerritoryName unicode_string The name of the territory.

sslCertBeginDate BrokerDate The date of the Broker's certificate became valid.

sslCertSerialNumber unicode_string The serial number of the Broker's certificate. only set if authProtocol is set to "SSL".

sslCertEndDate BrokerDate The date the Broker's certificate expires.

sslCertStatus unicode_string The status of the other Broker's certificate. This field is only set if authProtocol is set to "SSL".

sslDistinguishedName unicode_string The distinguished name s of the other Broker's certificate. This field is only set if authProtocol is set to "SSL".

sslIssuerDistinguishedName unicode_string The distinguished name s of the issuer of the other Broker's certificate. This field is only set if authProtocol is set to "SSL".




See Also:

BrokerAdminClient.createTerritory

getTerritoryInfo

BrokerTerritoryInfo getTerritoryInfo() throws BrokerException

Returns a BrokerTerritoryInfo object that contains the territory settings for the Broker to which this client is connected.

gateway_pause boolean A flag indicating whether outbound traffic from this gateway Broker to territory_name is enabled or disabled (paused). Will be true if outbound traffic to territory_name has been paused. See setTerritoryGatewayPause.

gateway_pause_time date The time when the gateway was paused. If outbound traffic is not currently paused for territory_name, this parameter will be 0.

gateway_pause_client String The client id of the BrokerAdminClient that paused the gateway. If outbound traffic is not currently paused for territory_name, this parameter will be empty.

gateway_pause_session integer The session id from which the gateway was paused. If outbound traffic is not currently paused for territory_name, the value will be 0.



BrokerNoPermissionException The BrokerAdminClient does not have permission to get the territory statistics.

BrokerNotInTerritoryException 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:






brokers structure[] The time the event type was created. This includes changes to the definition, the time-to-live setting, or any infoset. A value of zero means there have been no changes since this event type was created

brokers.authProtocol unicode_string The protocol being used to authenticate the Broker. Only set if connectedFrom is not empty and authentication is used. Currently, the only supported value is "SSL".

brokers.authVersion unicode_string The version of the authentication protocol being used to authenticate the Broker. Only set if authProtocol is not empty. Currently supported values are "2" and "3".

brokers.brokerHost unicode_string The Broker host name.

brokers.brokerName unicode_string The Broker Server name.

brokers.connectedFrom boolean Set to true if the Broker is currently connected.

brokers.description unicode_string The Broker's description.



brokers.encryptLevel unicode_string The level of encryption being used. Only set if encryptProtocol is set. Currently supported values are "USDomestic" and "USExport".

brokers.encryptProtocol unicode_string The encryption protocol being used. Only set if connectedFrom is not empty. The only values currently supported is "SSL".

brokers.encryptVersion unicode_string The version of the encryption protocol being used. Only set if encryptProtocol is not empty. Currently supported values are "2" and "3".

brokers.lastConnectTime BrokerDate The time the Broker was last connected. Set to zero if never connected.

brokers.lastEventEnqueueTime BrokerDate The time an event was last enqueued for the Broker. Set to zero if no events have ever be enqueued.

brokers.lastEventForwardTime BrokerDate Time when an event of this type was last forwarded to the Broker. Set to zero if no events have been forwarded.

brokers.lastEventReceiveTime BrokerDate Time when an event was last received by the Broker. Set to zero if no events have been received.

brokers.numEventsEnqueued int Number of events that were enqueued for the Broker.

brokers.numEventsForwarded int Number of events that were forwarded to the Broker.

brokers.numEventsReceived int The number of events received by the Broker.

brokers.queueByteSize int The current size, in bytes, of the Broker's queue.

brokers.queueHighestLength int The highest number of events in the Broker's queue.




brokers.queueHighestLengthTime BrokerDate Time when queueHighestLength was last changed.

brokers.queueLength int The number of events currently in the Broker's queue.

brokers.sslCertBeginDate BrokerDate The date of the Broker's certificate became valid.

brokers.sslCertSerialNumber unicode_string The serial number of the Broker's certificate. only set if authProtocol is set to "SSL".

brokers.sslCertEndDate BrokerDate The date the Broker's certificate expires.

brokers.sslCertStatus unicode_string The status of the Broker's certificate. This field is only set if authProtocol is set to "SSL".

brokers.sslDistinguishedName unicode_string The distinguished name s of the Broker's certificate. This field is only set if authProtocol is set to "SSL".

brokers.sslIssuerDistinguishedName unicode_string The distinguished name s of the issuer of the other Broker's certificate. This field is only set if authProtocol is set to "SSL".


territoryName unicode_string The name of the territory.








See Also:

BrokerAdminClient.createTerritory, BrokerAdminClient.getBrokersInTerritory, BrokerAdminClient.joinTerritory, BrokerAdminClient.leaveTerritory, and BrokerAdminClient.removeBrokerFromTerritory

getTransactions

BrokerEvent getTransactions() throws BrokerException;

Returns a BrokerEvent containing the following information for the current transactions under the Broker transaction manager.

Field Name Type

now BrokerDate

transaction struct[]






















See Also:

BrokerAdminClient.getTransactionsByClient

getTransactionsByClient

BrokerEvent getTransactionsByClient( String client_id) throws BrokerException;

Returns a BrokerEvent containing the following information for a given transactional client.

Field Name Type

now BrokerDate

transactions[] struct[]


















BrokerInvalidClientException The client has been destroyed or disconnected.

BrokerInvalidClientIdException client_id contains illegal characters.

BrokerNullParameterException client_id is null.

BrokerNoPermissionException Client does not have sufficient permissions.



See Also:

BrokerAdminClient.getTransactions

join method

joinTerritory

BrokerJoinFailure joinTerritory( String broker_host, String broker_name) throws BrokerException

Causes this client's Broker join the territory of the Broker with the specified broker_name that is running on broker_host. If the join operation is successful, a null value is returned. Otherwise, a BrokerJoinFailureInfo object will be returned that describes the client groups and event types defined for this Broker that conflict with the territory's definitions.

For more information on the concept of territories, see Administering webMethods Broker.


broker_name The name of the Broker whose territory this Broker is to join. whose territory this Broker is to join. This parameter may not be null.



BrokerInTerritoryException This client's Broker is already a member of a territory.



BrokerNotInTerritoryException The Broker specified by broker_name is not a member of a territory.


BrokerOutOfRangeException There is another Broker in the specified territory with the same name

BrokerSecurityException If the territory requires SSL and the joining Broker does not support SSL.



See Also:

BrokerAdminClient.createTerritory, BrokerAdminClient.getBrokersInTerritory, BrokerAdminClient.getTerritoryStats, BrokerAdminClient.leaveTerritory, and BrokerAdminClient.removeBrokerFromTerritory

leave Methods

leaveCluster

void leaveCluster( int msecs, boolean forced) throws BrokerException

Causes this client's Broker to leave its cluster. This operation may take time to complete because it requires communicating with other Brokers in the cluster. If msecs is not set to -1, a time-out exception may be thrown before the operation is completed. If forced is true, then the Broker will leave the cluster even if it cannot communicate with the other members of the cluster within the Broker's timeout period.

Note: Any other operation made on the Broker while this operation is in progress may also block and time out.


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

msecs The number of milliseconds to wait for this operation to complete before timing out. If set to -1, this operation will never time out.

forced If set to true, the Broker will leave the cluster even if it cannot contact other cluster members within the specified time out interval.








See Also:

BrokerAdminClient.createCluster, BrokerAdminClient.getBrokersInCluster, BrokerAdminClient.getClusterStats, BrokerAdminClient.addBrokerToCluster, and BrokerAdminClient.removeBrokerFromCluster

leaveTerritory

void leaveTerritory( int msecs, boolean forced) throws BrokerException

Causes this client's Broker to leave its territory. This operation may take time to complete because it requires communicating with other Brokers in the territory. If msecs is not set to -1, a time-out exception may be thrown before the operation has completed.

Note: Any other operation made on the Broker while this operation is in progress may also block and time out.


See Also:

BrokerAdminClient.createTerritory, BrokerAdminClient.getBrokersInTerritory, BrokerAdminClient.getTerritoryStats, BrokerAdminClient.joinTerritory, and BrokerAdminClient.removeBrokerFromTerritory

msecs The number of milliseconds to wait for this operation to complete before timing out. If set to -1, this operation will never time out.

forced If set to true, the Broker will leave the territory even if it cannot contact other territory members within the specified time out interval.







new Method

newOrReconnectAdmin

static BrokerAdminClient newOrReconnectAdmin( String broker_host, String broker_name, String client_id, String client_group, String app_name, BrokerConnectionDescriptor desc) throws BrokerException

Attempts to create a new BrokerAdminClient with an event queue and zero subscriptions. If a BrokerAdminClient with the same client_id already exists, this client will be reconnected.

Note: For information on Broker name, client group name, and client identifier restrictions, see the webMethods Broker Client Java API Programmer’s Guide.

When finished with the BrokerAdminClient, the application is responsible for calling BrokerClient.disconnect or BrokerClient.destroy.

Note: When reconnecting, the client state sharing that was set when the BrokerAdminClient was originally created will be used. Client state sharing can only be enabled or disabled when creating new Broker clients, regardless of the information contained in the BrokerAdminDescriptor.

broker_host The name of the host where the Broker is running that the new Broker client will use. Specified in the form <broker_host_name>:<port_number>. If the port number is omitted, the default port number will be used. For example: MyHost:12000

broker_name The name of the Broker Server. If set to null, the default Broker name is used.

client_id The client identifier, identifying the client as the one that was previously disconnected. See the webMethods Broker Client Java API Programmer’s Guide for more information on client identifiers.



desc The connection descriptor to use for the client. If set to null, a default connection will be established which may be shared with other clients.



See Also:

BrokerAdminClient.BrokerAdminClient, BrokerAdminClient.reconnectAdmin, as well as BrokerClient.destroy and BrokerClient.disconnect (described in the webMethods Broker Client Java API Programmer’s Guide)

reconnect Method

reconnectAdmin

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


BrokerClientContentionException Another Broker client is already using the specified client_id. For clients with shared state, the maximum number of reconnects has been exceeded.




BrokerNoPermissionException Permission to join the client_group as an administrative client was denied.


BrokerNullParameterException The broker_host, client_id, client_group, or app_name parameter is null.




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



Reconnects a previously disconnected BrokerAdminClient to a Broker so that the client can resume event processing. The client_id parameter identifies the BrokerAdminClient as one you previously disconnected using BrokerClient.disconnect.

Note: For information on Broker name, client group name, and client identifier restrictions, see the webMethods Broker Client Java API Programmer’s Guide.

When finished with the BrokerAdminClient, the application is responsible for calling BrokerClient.disconnect or BrokerClient.destroy.

In addition to reconnecting a previously disconnected BrokerAdminClient, this method may be used to connect a BrokerAdminClient that wants to share client state with another BrokerAdminClient.

Note: When reconnecting, the client state sharing that was set when the BrokerAdminClient was originally created will be used, regardless of the settings in the BrokerConnectionDescriptor.

broker_name The name of the Broker Server. If set to null, the default Broker name is used.

client_id The client identifier, identifying the client as the one that was previously disconnected. See the webMethods Broker Client Java API Programmer’s Guide for more information on client identifiers.

desc The connection descriptor to use for the client. If set to null, a default connection will be established which may be shared with other clients.


BrokerClientContentionException Another Broker client is already using the specified client_id. For clients with shared state, the maximum number of reconnects has been exceeded.




BrokerNoPermissionException Permission to join the client_group as an administrative client was denied.


BrokerNullParameterException The broker_host or client_id parameter is null.



See Also:

BrokerAdminClient.BrokerAdminClient and BrokerAdminClient.newOrReconnectAdmin, as well as BrokerClient.destroy and BrokerClient.disconnect (described in the webMethods Broker Client Java API Programmer’s Guide)

release Method

releaseChangeLock

void releaseChangeLock() throws BrokerException

Releases the change lock being held by this client for its Broker.

An exception will be thrown if the Broker to which this client is connected is not currently locked, or if the lock is held by another client.

See Also:

BrokerAdminClient.acquireChangeLock

remove Methods

removeBrokerFromCluster

void removeBrokerFromCluster( String broker_host, String broker_name) throws BrokerException




BrokerBadStateException The client's Broker is currently not locked or the lock is being held by another client.






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.


See Also:

BrokerAdminClient.createCluster, BrokerAdminClient.getBrokersInCluster, BrokerAdminClient.getClusterStats, BrokerAdminClient.addBrokerToCluster, and BrokerAdminClient.leaveCluster.

removeBrokerFromTerritory

void removeBrokerFromTerritory( String broker_host, String broker_name) throws BrokerException


broker_name The name of the Broker Server to be removed from the cluster to which this client's Broker belongs.


BrokerHostNotFoundException The specified host cannot be located.



BrokerNotInClusterException The Broker to which this BrokerAdminClient is connected is not in any cluster.


BrokerOutOfRangeException An attempt was made to remove the current Broker.

BrokerUnknownBrokerNameException The specified broker_name on the specified broker_host is not a member of the cluster.



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.


See Also:

BrokerAdminClient.createTerritory, BrokerAdminClient.getBrokersInTerritory, BrokerAdminClient.getTerritoryStats, BrokerAdminClient.joinTerritory, and BrokerAdminClient.leaveTerritory

set Methods

setBrokerDescription

void setBrokerDescription( String description) throws BrokerException


broker_name The name of the Broker Server to be removed from the territory to which this client's Broker belongs.





BrokerNotInTerritoryException The Broker to which this BrokerAdminClient is connected is not in any territory.


BrokerOutOfRangeException An attempt was made to remove the current Broker.

BrokerUnknownBrokerNameException The specified broker_name on the specified broker_host is not a member of the territory.

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



Sets the description for the Broker to which this BrokerAdminClient is connected. The description is a comment field that will be displayed by the webMethods Broker administration tools and can contain any information you want.

See Also:

BrokerAdminClient.getBrokerDescription

setClientGroupAccessLabelRequired

void setClientGroupAccessLabelRequired( String client_group_name, boolean required) throws BrokerException

Sets whether or not an access label is required for creating a client in the specified client group. A client group's current access label requirements can be determined using the BrokerAdminClient.getClientGroupInfo method.

See Also:

BrokerAdminClient.getClientGroupInfo



BrokerNoPermissionException The BrokerAdminClient does not have permission to set the Broker's description.

BrokerNullParameterException The description parameter is null.

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

required If set to true, an access label will be required.



BrokerNoPermissionException The BrokerAdminClient does not have permission to modify the client group.





setClientGroupACL

void setClientGroupACL( String client_group_name, BrokerAcessControlList acl) throws BrokerException

Sets the list of names that are allowed to create Broker clients which belong to the specified client group.

See AccessControlList for more information.

See Also:

BrokerAdminClient.getClientGroupACL

setClientGroupCanPublishList

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

Sets the list of event type names that can be published or delivered by the specified client group. Any event type names previously set in the can-publish list will be replaced by the new list.

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

acl The access control list to set.


BrokerInvalidAccessListException The access control list is invalid.


BrokerNoPermissionException The BrokerAdminClient does not have permission to set the client group's Access Control List.

BrokerNullParameterException The client_group_name or acl parameter is null.


client_group_name A string containing the name of the client group whose can-publish list is to be set.

event_type_names An array of strings containing the event type names to be set as the can-publish list.



See Also:

BrokerAdminClient.getClientGroupCanPublishList, BrokerAdminClient.getClientGroupCanSubscribeList, and BrokerAdminClient.setClientGroupCanSubscribeList

setClientGroupCanSubscribeList

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

Sets the list of event type names to which members of the client group can subscribe or which may be delivered to members of the client group. Any event type names previously set in the can-subscribe list will be replaced by the new list.



BrokerNoPermissionException The BrokerAdminClient does not have permission to set the client group's can-publish list.

BrokerNullParameterException The client_group_name or event_type_names parameter was null or an entry in the event_type_names array is null.


BrokerUnknownEventTypeException One of the event types specified in the event_type_names array does not exist on the Broker. If this exception is thrown, the client group's original can-publish list will not be altered.

client_group_name A string containing the name of the client group whose can-subscribe list is to be set.

event_type_names An array of strings containing the event type names to be set as the can-subscribe list.



BrokerNoPermissionException The BrokerAdminClient does not have permission to set the client group's can-publish list.

BrokerNullParameterException The client_group_name parameter was null or an entry in the event_type_names array is null.



See Also:

BrokerAdminClient.getClientGroupCanSubscribeList, BrokerAdminClient.getClientGroupCanPublishList, and BrokerAdminClient.setClientGroupCanPublishList

setClientGroupDescription

void setClientGroupDescription( String client_group_name, String description) throws BrokerException

Sets the description of the specified client group. You can use the BrokerAdminClient.getClientGroupInfo method to retrieve the description.

See Also:

BrokerAdminClient.getClientGroupInfo and BrokerAdminClient.getClientGroupNames


BrokerUnknownEventTypeException One of the event types specified in the event_type_names array does not exist on the Broker. If this exception is thrown, the client group's original can-subscribe list will not be altered.

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

description A string containing the description to be set for the client group.



BrokerNoPermissionException The BrokerAdminClient does not have permission to set the client group's description.

BrokerNullParameterException The client_group_name or description parameter is null.





setClientGroupLogAcknowledgeList

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

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

setClientGroupLogPublishList

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

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


event_type_names List of the event type names to be logged.



BrokerNoPermissionException The client does not have permission to modify the client group.

BrokerNullParameterException If client_group_name or event_type_names is null, or if any entry in the array is null.

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


event_type_names List of the event type names to be logged.



BrokerNoPermissionException The client does not have permission to modify the client group.

BrokerNullParameterException If client_group_name or event_type_names is null, or if any entry in the array is null.



setClientGroupRequiredEncryption

void setClientGroupRequiredEncryption( String client_group_name, int level) throws BrokerException

Set the required encryption for the specified client group.

This client group's current value can be acquired using the BrokerAdminClient.getClientGroupInfo method.

See Also:

BrokerAdminClient.getClientGroupInfo

setClientInfosetById

void setClientInfosetById( String client_id, BrokerEvent infoset) throws BrokerException

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

client_group_name The name of the client group whose required encryption level is being set.

level The level of encryption required by the client group. Must be a BrokerConnectionDescriptorENCRYPT_LEVEL_* values described in the webMethods Broker Client Java API Programmer’s Guide.



BrokerNoPermissionException The BrokerAdminClient does not have permission to modify the properties of the specified client group.

BrokerNullParameterException The client _group parameter is null.

BrokerOutOfRangeException The parameter level contains an invalid value.

BrokerUnknownClientGroupException The specified client group does not exist on the Broker.

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




Sets the client infoset for the Broker client with the specified client_id. The infoset is passed as a BrokerEvent for convenience.

Note: For information on infoset name and infoset field name restrictions, see the webMethods Broker Client Java API Programmer’s Guide.

See Also:

BrokerAdminClient.getClientInfosetById

setClientLastPublishSequenceNumberById

void setClientLastPublishSequenceNumberById( String client_id, long seqn) throws BrokerException

Sets the high publisher sequence number for the specified Broker client. This is sequence number from the event most recently by the client. The Broker stores this sequence number and uses it to recognized and discard duplicate events which may be published by the Broker client.

The current last-published sequence number can be acquiring using the BrokerAdminClient.getClientInfoById method.

infoset The infoset to be set for the Broker client.



BrokerNoPermissionException The BrokerAdminClient does not have permission to modify the properties of the specified Broker client.

BrokerNullParameterException The client_id or infoset parameter is null.


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

seqn The new last-published sequence number to set.





See Also:


setClientStateShareLimitById

void setClientStateShareLimitById( String client_id, int limit) throws BrokerException

Sets the number of clients which can simultaneously connect using the same client identifier as the Broker client with the specified client_id. You can obtain the current state sharing limit by using the BrokerAdminClient.getClientInfoById method.

Note: This method can only be used to alter those Broker clients who are currently enabled to share their state. For more information, refer to the BrokerConnectionDescriptor class description in the webMethods Broker Client Java API Programmer’s Guide.


getClientIds



BrokerNoPermissionException The BrokerAdminClient does not have permission to modify the properties of the specified Broker client.


BrokerOutOfRangeException The seqn parameter is less than zero.


client_id A string containing the client identifier whose state share limit is to be set.

limit The new limit to be set. Setting a value of -1 indicates there is no limit to the number of clients that may share state with the specified client.



BrokerNoPermissionException The BrokerAdminClient does not have permission to modify the client's queue or the client is not currently sharing its state.




See Also:


setClusterACL

void setClusterACL( BrokerAccessControlList acl) throws BrokerException

Sets the access control list used by Broker's in this cluster to accept connections from other Brokers in the cluster. Changing the cluster's ACL will not cause existing inter-Broker connections to fail.

For more information on clusters, see Administering webMethods Broker.

Important! If you use this method to disallow a user identity that is currently being used by a member of the cluster, your cluster will become partially disconnected.

See Also:

BrokerAdminClient.getClusterACL


BrokerOutOfRangeException The limit parameter is zero or less than -1.


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


BrokerInvalidAccessListException The acl variable does not contain a valid access control list.


BrokerNoPermissionException The BrokerAdminClient does not have permission to modify the Broker.

BrokerNotInClusterException The Broker to which this client is connected is not part of a cluster.





setClusterGatewayACL

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

Set the access control list (ACL) which this Broker will use to accept connections from the other Broker in he cluster gateway.

The access control list can contain either one entry or no entries in each of the user and authenticator lists. Changing the current access control list will not cause an existing gateway connection to fail.

Important! If you use this method to disallow a user identity that is currently being used by the other Broker in the cluster gateway, the gateway will become disconnected.

See Also:

BrokerAdminClient.getClusterGatewayACL

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

broker_name The name of the Broker in the specified remote cluster to which the ACL is to be set.

acl The access control list.






BrokerNullParameterException The cluster_name, broker_name or acl parameter is null.

BrokerOutOfRangeException The acl contains more than one user entry or more than one authenticator entry.




setClusterGatewayKeepAlive

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

This method enables or disables the keep-alive feature on the cluster gateway Broker. When enabled, the gateway Broker issues 'keep-alive' messages to the cluster specified in cluster-name.

The keep-alive feature is useful when the firewalls separating gateway Brokers are programmed to drop connections that are idle for extended periods. To prevent the firewall from dropping the connection between the gateway Brokers, you use the keep-alive feature to generate enough traffic to keep the connection alive.

Setting KeepAlive to a positive number instructs the gateway Broker to issue keep-alive messages when its connection to cluster_name or broker_name is idle longer than the KeepAlive period (in seconds).

For more information about the keep-alive feature, see “Maintaining a Connection Between Gateway Brokers” on page 100.

cluster_name The name of the cluster to which you want the gateway Broker to issue keep-alive messages.

broker_name The name of the gateway Broker in the specified remote cluster you want to enable or disable keep-alive messages.

KeepAlive The frequency, in number of seconds, with which the gateway Broker will issue keep-alive messages to cluster_name. Set KeepAlive to 0 to disable keep-alive messages.




BrokerOutOfRageException The value of KeepAlive is less than Zero (0).




BrokerIncompatibleVersionException Gateway Broker does not support the keep-alive feature.



See also BrokerAdminClient.getClusterGatewayKeepAlive

setClusterGatewayPause

void setClusterGatewayPause( String cluster_name, String broker_name, boolean pause) throws BrokerException

This methods prevents the gateway Broker from forwarding events to the cluster in cluster_name. Once the gateway has been paused, the gateway Broker will hold events for the specified cluster until the pause state is explicitly cleared by setting pause to false.

To check whether outbound events to another cluster have been are paused, check the gateway_pause value returned by getClusterGatewayStats.

cluster_name The name of the cluster whose events you want the gateway Broker to hold.

broker_name The name of the gateway Broker in the specified cluster to which you want to prevent from forwarding events.

pause Flag indicating whether the gateway Broker is to pause or resume the transmission of events to the cluster in cluster_name. Set to true to halt the forwarding of events to cluster_name. Set to false to resume sending events to cluster_name.



BrokerNullParameterException The cluster_name or broker_name is null.

BrokerBadStateException The cluster gateway is already paused or resumed.


BrokerNotInClusterException The Broker to which this client is connected is not a member of a cluster.


BrokerIncompatibleVersionException The gateway Broker does not support this feature.

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



setClusterGatewayRefuseAllUpdates

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

Set whether a cluster gateway will refuse all updates to shared document types made in a connected cluster.

If the refuse_updates parameter is set to true, all updates from the specified cluster are refused. However, the individual settings for each event type are retained, so that when refuse_updates parameter is set back to false, the original event type settings are reset.

See Also:

BrokerAdminClient.getClusterGatewayRefuseAllUpdates

setClusterGatewaySecurity

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

cluster_name The name of the cluster to which updates are refused.

broker_name The name of the Broker in the specified cluster. This Broker is used to identify the right gateway link for setting this permission.

refuse_updates Specify whether the cluster will refuse all updates from a neighboring cluster connected by a gateway (true).







cluster_name The name of the cluster whose gateway security is to be set.

broker_name The name of the Broker in the specified remote cluster to which this Broker is connected.



Sets the type of authentication and level of encryption used for the cluster gateway. The remote Broker that makes up the other half of the gateway should be properly configured for the new settings prior to changing the settings on the local Broker. The changes may take some time to take effect.

You can get the current settings by using getLocalClusterGateways() or getAllClusterGateways() methods. The auth_type value can be any of the AUTH_TYPE_* values. The encrypt_level value can be any of the BrokerConnectionDescriptor.ENCRYPT_LEVEL_* values.

Important! Use this method with care because changing the security setting may cause the gateway to become disconnected. For example, setting SSL authentication or encryption when the remote Broker is not configured for SSL will cause the gateway to become disconnected.

See also BrokerAdminClient.getAllClusterGateways and BrokerAdminClient.getLocalClusterGateways

setClusterGatewaySharedEventTypes

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

auth_type The type of authentication to set for the gateway, specified as one of the AUTH_TYPE_* values defined by BrokerAdminClient.

encrypt_level The level of encryption to set for the gateway, specified as one of the ENCRYPT_LEVEL_* values defined by BrokerConnectionDescriptor, described in the webMethods Broker Client Java API Programmer’s Guide.






BrokerOutOfRangeException The auth_type or encrypt_level parameter contains an invalid value.




Sets the complete list of shared event types on for a cluster gateway. The is_synchronized field in each element of infos is ignored.

Note: To configure gateway event type sharing, first save the can-subscribe settings on both sides of the gateway and then save the can-publish settings. It is important to set the can-subscribe settings before the can-publish settings and to set them in separate invocations of this method.

The subscribe_filter variable in each element of infos can be set to a filter string to control the events which are forwarded through the gateway. If you do not want event filtering to take place across the gateway, this member must be set to a null string. See the webMethods Broker Client Java API Programmer’s Guide for complete information on event filtering


cluster_name The name of the cluster whose shared event types are to be set.

broker_name The name of the Broker in specified remote cluster.









BrokerNullParameterException The cluster_name, broker_name, or infos parameter is null, or an element in infos is null, or an element in infos has a nullevent_type_name.





See Also:

BrokerAdminClient.getClusterGatewaySharedEventTypes

setClusterPrimaryGateway

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

Set the primary gateway connection from this Broker to the remote cluster specified by cluster_name and broker_name.

setClusterSecurity

void setClusterSecurity( int auth_type, int encrypt_level) throws BrokerException

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

cluster_name The name of the cluster to which the primary gateway connection has to be set.

broker_name The name of the Broker in the specified cluster that will be used for the primary gateway connection.







BrokerIncompatibleVersionException The Broker does not support cluster gateways. Broker Server version 8.2 and above support cluster gateways.




Set the type of authentication and level of encryption used for the cluster. All Brokers in the cluster must be properly configured for the new settings and the changes may take some time to be propagated throughout the cluster.

Important! Use this method with care because changing the security setting may cause the cluster to become partially disconnected. For example, setting SSL authentication or encryption when one or more Brokers are not configured for SSL will cause the cluster to become partially disconnected.

See also BrokerAdminClient.getClusterInfo

setClusterStaticGatewayForwarding

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

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

auth_type The type of authentication to set for the cluster, specified as one of the AUTH_TYPE_* values defined by BrokerAdminClient.

encrypt_level The level of encryption to set for the cluster, specified as one of the ENCRYPT_LEVEL_* values defined by BrokerConnectionDescriptor, described in the webMethods Broker Client Java API Programmer’s Guide.






cluster_name The name of the cluster to which you want to enable or disable static gateway forwarding.

broker_name The name of the Broker used to identify the correct gateway link for enabling or disabling static gateway forwarding.

enable Specify whether the cluster will have static gateway forwarding to the other cluster connected by a gateway. The default is true.



setEventAdminTypeDef

void setEventAdminTypeDef( BrokerAdminTypeDef type_def) throws BrokerException

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

See Also:

BrokerAdminClient.destroyEventType, BrokerAdminClient.destroyEventTypes, BrokerAdminClient.getEventAdminTypeDef, BrokerAdminClient.getEventAdminTypeDefs, BrokerAdminClient.getEventAdminTypeDefsByScope, and BrokerAdminClient.setEventAdminTypeDefs

setEventAdminTypeDefs

void setEventAdminTypeDefs( BrokerAdminTypeDef type_defs[]) throws BrokerException

Sets the event type definition for each of the event types specified in the type_defs array. If an event type in the array does not exist on the Broker, it will be created.






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



BrokerNoPermissionException The BrokerAdminClient does not have permission to modify the event type's definition or, if the event type is new, to create a new event type definition.

BrokerNullParameterException The type_def parameter is null.

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



Note: If any entry in type_defs is found to be null, no event type definition will be set or modified.

See Also:

BrokerAdminClient.destroyEventType, BrokerAdminClient.destroyEventTypes, BrokerAdminClient.getEventAdminTypeDef, BrokerAdminClient.getEventAdminTypeDefs, BrokerAdminClient.getEventAdminTypeDefsByScope, and BrokerAdminClient.setEventAdminTypeDef

setEventLogging

void setEventLogging( boolean enabled) throws BrokerException

This method allows you to enable or disable event logging on each Broker. If enable_event_log is false(0), logging will be disabled. No events will be logged. If enable_event_log is true(1), logging will be enabled. Events published and acknowledged will be logged.

setEventTypeInfoset

void setEventTypeInfoset( String event_type_name, String infoset_name, BrokerEvent infoset) throws BrokerException

Sets the infoset for the specified event type. The infoset is passed as a BrokerEvent, for convenience. If the infoset does not currently exist on the Broker, it will be created.

Note: For information on infoset name and infoset field name restrictions, see the webMethods Broker Client Java API Programmer’s Guide.



BrokerNoPermissionException The BrokerAdminClient does not have permission to modify the event type's definition or, if the event type is new, to create a new event type definition.

BrokerNullParameterException The type_defs parameter is null or any array entry is null.

event_type_name The event type with which the infoset is associated.

infoset_name The name of the infoset to set. If null, the type name of the event will be used as the infoset name.

infoset A BrokerEvent object which represents the infoset.



See Also:

BrokerAdminClient.destroyEventTypeInfoset, BrokerAdminClient.destroyEventTypeInfosets, and BrokerAdminClient.setEventTypeInfosets, as well as BrokerClient.getEventTypeInfoset and BrokerClient.getEventTypeInfoset (described in the webMethods Broker Client Java API Programmer’s Guide)

setEventTypeInfosets

void setEventTypeInfosets( String event_type_name, BrokerEvent infosets[]) throws BrokerException

Sets the infosets for the specified event type. The infosets are passed as an array of BrokerEvent objects, for convenience. The type name of the infoset events are used as the infoset names. If an infoset found in the array does not currently exist on the Broker, it will be created.

Note: Previously existing infosets will not be destroyed.



BrokerInvalidEventTypeNameException The infoset_name is invalid.

BrokerNoPermissionException The BrokerAdminClient does not have permission to modify the event type's infoset.


BrokerUnknownEventTypeException The event_type_name does not exist on the Broker.

event_type_name The event type with which the infoset is associated.

infosets An array of BrokerEvent objects which represent the infosets for the event type.



BrokerNoPermissionException The BrokerAdminClient does not have permission to modify the event type's infosets.

BrokerNullParameterException The event_type_name or infosets parameter is null, or an entry in the infosets array is null.



See Also:

BrokerAdminClient.destroyEventTypeInfoset, BrokerAdminClient.destroyEventTypeInfosets, and BrokerAdminClient.setEventTypeInfoset, as well as BrokerClient.getEventTypeInfoset and BrokerClient.getEventTypeInfoset (described in the webMethods Broker Client Java API Programmer’s Guide)

setEventTypesAndClientGroups

BrokerSetFailureInfo setEventTypesAndClientGroups( String event_type_names_to_destroy[], String client_group_names_to_destroy[], BrokerCompleteEventType event_types[], BrokerCompleteClientGroup client_groups[], boolean forced) throws BrokerException

With one invocation of this method, you can create, modify, and destroy both event types and client groups on the Broker to which this administrative client is connected. All deletions take place first, then all the other values are either created, if they did not exist, or they are modified.

This method returns null if all operations completed successfully. If an error occurs, the returned BrokerSetFailureInfo object will contain the details. If there are any permission problems, then only permission problems are reported. If there are no permission


event_type_names_to_destroy A list of event types that are to be destroyed on the Broker. May be set to null if you do not wish to destroy any event types.

client_group_names_to_destroy A list of client groups that are to be destroyed on the Broker. May be set to null if you do not wish to destroy any client groups.

event_types A set of event types to be defined on the Broker. May be set to null if you do not wish to add or modify any event types.

client_groups A set of client group to be defined on the Broker. May be set to null if you do not wish to add or modify any client groups.

forced If set to false, any failure in destroying or adding either a client group or an event type will be reported in the return value and no changes will be made to the Broker. If set to true, failures may still be reported in the return value, but all changes that can be made to the Broker will be made.




problems, then only dependency failures are reported. If force is set to true, then as much work as possible is completed. Any permission errors will cause this method to fail. Any dependency problem will be forced if force is set to true.

Any of the first four arguments may be null if you do not wish to destroy, create, or modify an event type or client group.

If one of the event_types or client_groups elements specified already exists on the Broker, it will be updated with the new settings. If a variable in one of the event_types or client_groups elements is null, that aspect of the event type or client group will not be changed.

If the infosets variable in an event_types element is not null, the replace_all_infosets flag in that element will be used to determine if the infosets are merged in or if they completely replace the existing infosets.

To delete infosets using this method, you must obtain a list of the existing infosets, remove the ones you want to delete, and then set the replace_all_infosets flag to true.

See Also:

BrokerAdminClient.getEventAdminTypeDef, BrokerAdminClient.getEventAdminTypeDefs, BrokerAdminClient.getClientGroupInfo, BrokerAdminClient.getClientGroupInfos


BrokerInvalidAccessListException An ACL, specified in one of the client_groups elements, is invalid.


BrokerInvalidClientGroupException A client group name, specified in one of the client_groups elements, is invalid.

BrokerInvalidEventTypeNameException An event type name, specified in one of the event_types elements, is invalid.

BrokerNullParameterException An element in event_types or client_groups is null, or a BrokerCompleteEventTypetype_def field is null, or a BrokerCompleteClientGroupclient_group_info field is null, of the name field in a client_group_info is null.

BrokerOutOfRangeException An element in client_groups specifies an invalid life_cycle or storage_type value.

BrokerUnknownEventTypeException An element in client_groups specified an unknown event type name in a client group's can-publish or can-subscribe list.



setPostPrepareTimeout

void setPostPrepareTimeout( int timeout_secs) throws BrokerException

Specifies the default value, in seconds, of the post-prepare time-out period. The post-prepare time-out period is the period of time between the point when a transaction is prepared and when it is committed.

See Also:

BrokerAdminClient.getPostPrepareTimeout and BrokerAdminClient.setPostPrepareTimeoutAction

setPostPrepareTimeoutAction

void setPostPrepareTimeoutAction( int action) throws BrokerException

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

timeout_secs The post-prepare timeout in seconds.




BrokerOutOfRangeException The timeout_secs value is out of range.


action BrokerAdminClient.TRANSACTION_ROLLBACK or BrokerAdminClient.TRANSACTION_COMMIT.




BrokerOutOfRangeException The value of action is invalid.



See Also:

BrokerAdminClient.getPostPrepareTimeoutAction and BrokerAdminClient.setPostPrepareTimeout

setPrePrepareTimeout

void setPrePrepareTimeout( int timeout_secs) throws BrokerException

Specifies the default value, in seconds, of the pre-prepare time-out period. The pre-prepare time-out period is the period of time between the point when a transaction begins until it is asked to prepare.

See Also:

BrokerAdminClient.getPrePrepareTimeout

setRecoverMode

void setRecoverMode(int mode) throws BrokerException

Specifies the recover mode for Broker transaction manager. The recover mode setting determines whether clients are permitted to recover any recoverable transactions (RECOVER_GLOBAL) or only those transaction in which they participated (RECOVER_RESTRICTED).


timeout_secs The pre-prepare timeout in seconds.






mode RECOVER_RESTRICTED or RECOVER_GLOBAL.




See Also:

BrokerAdminClient.getRecoverMode

setRemoteBrokerKeepAlive

int setRemoteBrokerKeepAlive( String broker_name, int KeepAlive) throws BrokerException

This method enables or disables the keep-alive feature on the remote Broker. When enabled, the remote Broker issues 'keep-alive' messages to the Broker specified in Broker-name. Both Brokers must belong to the same territory.

The keep-alive feature is useful when the firewalls separating Brokers are programmed to drop connections that are idle for extended periods. To prevent the firewall from dropping the connection between the Brokers, you use the keep-alive feature to generate enough traffic to keep the connection alive.

Setting KeepAlive to a positive number instructs the remote Broker to issue keep-alive messages when its connection to broker_name is idle longer than the KeepAlive period (in seconds).





broker_name The name of the Broker to which you want the remote Broker to issue keep-alive messages.

KeepAlive The frequency, in number of seconds, with which the remote Broker will issue keep-alive messages to broker_name. Set KeepAlive to 0 to disable keep-alive messages.



BrokerNullParameterException broker_name is null

BrokerOutOfRageException KeepAlive value is < 0.

BrokerIncompatibleVersionException A Broker does not support the keep-alive feature.



For more information, see “Maintaining a Connection Between Brokers in a Territory” on page 96.

See also BrokerAdminClient.getRemoteBrokerKeepAlive

setStaticGatewayForwarding

void setStaticGatewayForwarding( String territory_name, boolean enable) throws BrokerException

Specifies if static gateway forwarding is enabled or disabled. Set to true to enable static gateway forwarding; set to false to disable.

Note: The default value of setStaticGatewayForwarding is version-dependent. Static gateway forwarding was introduced in version 6.5. For that version and later, the default value is true and static gateway forwarding is enabled.

See Also:

BrokerAdminClient.getStaticGatewayForwarding

setTerritoryACL

void setTerritoryACL( BrokerAccessControlList acl) throws BrokerException

Sets the access control list used by Broker's in this territory to accept connections from other Brokers in the territory. Changing the territory's ACL will not cause existing inter-Broker connections to fail.

For more information on territories, see “Managing Broker Territories” on page 93.

territory_name name of the remote territory

enable state of static gateway forwarding


BrokerIncompatibleVersionException The gateway Broker on which the static forwarding option is applied to is an earlier version than webMethods Broker version 6.5.

BrokerNotInTerritoryException The gateway Broker is not in the territory.

BrokerNullParameterException territory_name is full.

BrokerUnknownTerritoryException On the current Broker, there is no local gateway to the specified remote territory.

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



Important! If you use this method to disallow a user identity that is currently being used by a member of the territory, your territory will become partially disconnected.

See Also:

BrokerAdminClient.getTerritoryACL

setTerritoryGatewayACL

void setTerritoryGatewayACL( String territory_name, BrokerAccessControlList acl) throws BrokerException

Set the access control list that the Broker to which this client is connected will use to accept connections from the remote Broker in the territory gateway.

The access control list can contain either one entry or no entries in each of the user and authenticator lists. Changing the current access control list will not cause an existing gateway connection to fail.

Important! If you use this method to disallow a user identity that is currently being used by the other Broker in the territory gateway, the gateway will become disconnected.







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

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






See Also:

BrokerAdminClient.getTerritoryGatewayACL

setTerritoryGatewayKeepAlive

void setTerritoryGatewayKeepAlive( String territory_name, int KeepAlive) throws BrokerException

This method enables or disables the keep-alive feature on the gateway Broker. When enabled, the gateway Broker issues 'keep-alive' messages to the territory specified in territory-name.

The keep-alive feature is useful when the firewalls separating gateway Brokers are programmed to drop connections that are idle for extended periods. To prevent the firewall from dropping the connection between the gateway Brokers, you use the keep-alive feature to generate enough traffic to keep the connection alive.




BrokerOutOfRangeException The acl contains more than one user entry or more than one authenticator entry.


territory_name The name of the territory to which you want the gateway Broker to issue keep-alive messages.

KeepAlive The frequency, in number of seconds, with which the gateway Broker will issue keep-alive messages to territory_name. Set KeepAlive to 0 to disable keep-alive messages.




BrokerOutOfRageException KeepAlive value is < 0.

BrokerIncompatibleVersionException Gateway Broker does not support the keep-alive feature.




Setting KeepAlive to a positive number instructs the gateway Broker to issue keep-alive messages when its connection to territory_name is idle longer than the KeepAlive period (in seconds).

For more information about the keep-alive feature, see “Maintaining a Connection Between Gateway Brokers” on page 100.

See also BrokerAdminClient.getTerritoryGatewayKeepAlive

setTerritoryGatewayPause

void setTerritoryGatewayPause( String territory_name, boolean pause) throws BrokerException

This methods prevents the gateway Broker from forwarding events to the territory in territory_name. Once the gateway has been paused, the gateway Broker will hold events for the specified territory until the pause state is explicitly cleared by setting pause to false.

To check whether outbound events to another territory have been are paused, check the gateway_pause value returned by getTerritoryGatewayStats.

territory_name The name of the territory whose events you want the gateway Broker to hold.

pause Flag indicating whether the gateway Broker is to pause or resume the transmission of events to the territory in territory_name. Set to true to halt the forwarding of events to territory_name. Set to false to resume sending events to territory_name.



BrokerNullParameterException territory_name is null.

BrokerBadStateException The territory gateway is already paused or resumed.


BrokerNotInTerritoryException The Broker to which this client is connected is not a member of a territory.


BrokerIncompatibleVersionException The gateway Broker does not support this feature.



setTerritoryGatewayRefuseAllUpdates

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

Set whether a territory gateway will refuse all updates to shared document types made in a connected territory.

If the refuse_updates parameter is set to true, all updates from the specified territory are refused, regardless of whether setTerritoryGatewayRefuseEventTypeUpdates is set to refuse updates to specific document types. However, the individual settings for each event type are retained, so that when refuse_updates parameter is set back to false, the original event type settings are reset.

See Also:

BrokerAdminClient.getTerritoryGatewayRefuseAllUpdates

setTerritoryGatewayRefuseEventTypeUpdates

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

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

territory_name The name of the territory to which updates are refused.

refuse_updates Specify whether the territory will refuse all updates from a neighboring territory connected by a gateway (true).







territory_name The name of the territory for which updates made 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.

See Also:

BrokerAdminClient.getTerritoryGatewayRefuseEventTypeUpdates

setTerritoryGatewaySecurity

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

Sets the type of authentication and level of encryption used for the territory gateway. The remote Broker that makes up the other half of the gateway should be properly configured for the new settings prior to changing the settings on the local Broker. The changes may take some time to take effect.

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







territory_name The name of the territory whose gateway security is to be set.

auth_type The type of authentication to set for the gateway, specified as one of the AUTH_TYPE_* values defined by BrokerAdminClient.

encrypt_level The level of encryption to set for the gateway, specified as one of the ENCRYPT_LEVEL_* values defined by BrokerConnectionDescriptor, described in the webMethods Broker Client Java API Programmer’s Guide.



Important! Use this method with care because changing the security setting may cause the gateway to become disconnected. For example, setting SSL authentication or encryption when the remote Broker is not configured for SSL will cause the gateway to become disconnected.

See also BrokerAdminClient.getAllClusterGateways and BrokerAdminClient.getLocalClusterGateways

setTerritoryGatewaySharedEventTypes

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

Sets the complete list of shared event types on for a territory gateway. The is_synchronized field in each element of infos is ignored.

Note: To configure gateway event type sharing, first save the can-subscribe settings on both sides of the gateway and then save the can-publish settings. It is important to set the can-subscribe settings before the can-publish settings and to set them in separate invocations of this method.

The subscribe_filter variable in each element of infos can be set to a filter string to control the events which are forwarded through the gateway. If you do not want event filtering to take place across the gateway, this member must be set to a null string. See the webMethods Broker Client Java API Programmer’s Guide for complete information on event filtering









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




See Also:

BrokerAdminClient.getTerritoryGatewaySharedEventTypes

setTerritorySecurity

void setTerritorySecurity( int auth_type, int encrypt_level) throws BrokerException








BrokerNullParameterException The territory_name or infos parameter is null, or an element in infos is null, or an element in infos has a nullevent_type_name.



BrokerUnknownTerritoryException There is no gateway to the specified territory from the local Broker.

auth_type The type of authentication to set for the territory, specified as one of the AUTH_TYPE_* values defined by BrokerAdminClient.

encrypt_level The level of encryption to set for the territory, specified as one of the ENCRYPT_LEVEL_* values defined by BrokerConnectionDescriptor, described in the webMethods Broker Client Java API Programmer’s Guide.



Set the type of authentication and level of encryption used for the territory. All Brokers in the territory must be properly configured for the new settings and the changes may take some time to be propagated throughout the territory.

Important! Use this method with care because changing the security setting may cause the territory to become partially disconnected. For example, setting SSL authentication or encryption when one or more Brokers are not configured for SSL will cause the territory to become partially disconnected.

See also BrokerAdminClient.getTerritoryInfo

BrokerAdminTypeDef

class BrokerAdminTypeDef extends java.lang.object

This class is used by BrokerAdminClient objects to administer the event type definitions stored by a Broker. It provides methods for administering a Broker's BrokerTypeDef object.

Many of the methods offered by this class make use of these BrokerTypeDef constants, described in the webMethods Broker Client Java API Programmer’s Guide.

The following table shows the BrokerTypeDef constants for each field type.






BrokerTypeDef Data Members Description

short FIELD_TYPE_BOOLEAN Represents a boolean.

short FIELD_TYPE_BYTE Represents a byte.

short FIELD_TYPE_CHAR Represents a char.

short FIELD_TYPE_DATE Represents a BrokerDate.

short FIELD_TYPE_DOUBLE Represents a double.

short FIELD_TYPE_FLOAT Represents a float.

short FIELD_TYPE_INT Represents a int.



Constructors

BrokerAdminTypeDef

BrokerAdminTypeDef( BrokerTypeDef normal_def) throws BrokerException

Creates a copy of a normal type definition.

BrokerAdminTypeDef

BrokerAdminTypeDef( BrokerAdminTypeDef type_def) throws BrokerException

Copy constructor.

short FIELD_TYPE_LONG Represents a long.

short FIELD_TYPE_SEQUENCE Represents a sequence field.

short FIELD_TYPE_SHORT Represents a short.

short FIELD_TYPE_STRING Represents a string.

short FIELD_TYPE_STRUCT Represents a structure field.

short FIELD_TYPE_UNKNOWN Represents a unknown field type.

Storage Type Description

STORAGE_GUARANTEED A two-phase commit process is used to store incoming events on the Broker. This offers the lowest performance, but very little risk of losing events if a hardware, software, or network failure occurs

STORAGE_VOLATILE Local memory is used to store incoming events on the Broker. This offers higher performance along with a greater risk of losing events if a hardware, software, or network failure occurs.

normal_def The BrokerTypeDef that this object is to administer.


BrokerNullParameterException The parameter normal_def parameter is null.

type_def The object being copied.

BrokerTypeDef Data Members Description



BrokerAdminTypeDef

BrokerAdminTypeDef( short type) throws BrokerException

Creates a new type definition for a non-event type with no name. Use this constructor when you want to create a BrokerAdminTypeDef object that represents an event field definition for use with the BrokerAdminTypeDef.setFieldDef method.

BrokerAdminTypeDef

BrokerAdminTypeDef( String type_name, short type) throws BrokerException

Creates a new type definition with the specified name and type.

Note: For information on event type name restrictions, see the webMethods Broker Client Java API Programmer’s Guide.


BrokerNullParameterException The parameter type_def parameter is null.

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


BrokerInvalidTypeException The type is FIELD_TYPE_EVENT or an invalid value.

type_name The name of the type being created.

type The type being created. Must be either FIELD_TYPE_EVENT or FIELD_TYPE_STRUCT.


BrokerInvalidEventTypeNameException The type_name is invalid.

BrokerInvalidTypeException The type is not FIELD_TYPE_EVENT or a FIELD_TYPE_STRUCT.

BrokerNullParameterException The parameter type_name parameter is null and type is FIELD_TYPE_EVENT.



Methods

clearField

void clearField( String field_name) throws BrokerException

Removes the specified field name from the event type definition.

See Also:

BrokerAdminTypeDef.clearFields

clearFields

void clearFields()

Deletes all fields from the event type definition.

clearModificationFlag

void clearModificationFlag()

Sets the modification flag for the event type definition such that subsequent invocations of the BrokerTypeDef.hasBeenModified method will return false.

See:

BrokerAdminTypeDef.hasBeenModified and BrokerAdminTypeDef.setModificationFlag

getBaseTypeName

String getBaseTypeName()

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


BrokerFieldNotFoundException Specified field_name does not exist in the event.

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

BrokerInvalidFieldNameException The field_name is invalid.

BrokerInvalidTypeException The field is not a field in a struct or event type.

BrokerNullParameterException The field_name parameter is null.


BrokerInvalidTypeException This object is not a struct or event type.



Returns the name of the event type definition without the scope qualifier.

See:

BrokerAdminTypeDef.getFieldDef, BrokerAdminTypeDef.getTypeName, and BrokerAdminTypeDef.setTypeName

getDescription

String getDescription() throws BrokerException

Returns the description for this event type definition.

See Also:

BrokerAdminTypeDef.setDescription

getFieldDef

BrokerAdminTypeDef getFieldDef( String field_name) throws BrokerException

Returns a BrokerAdminTypeDef containing the field definition for the specified field name.

See Also:

BrokerAdminTypeDef.getFieldNames, BrokerAdminTypeDef.getFieldType, BrokerAdminTypeDef.setFieldDef, and BrokerAdminTypeDef.setFieldType

getFieldNames

String[] getFieldNames( String field_name) throws BrokerException


BrokerInvalidTypeException This object's type is not FIELD_TYPE_EVENT.

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




BrokerInvalidFieldNameException The parameter field_name not valid.



Returns an array of strings containing the names of the fields in an event type or structure field. If field_name is set to a non-structure field, null will be returned.

See Also:

BrokerAdminTypeDef.getFieldDef and BrokerAdminTypeDef.getFieldType

getFieldType

short getFieldType( String field_name) throws BrokerException

Returns the type of the event or the field with the specified field_name. See the table in BrokerAdminTypeDef for a list of possible return values.

See Also:

BrokerAdminTypeDef.getFieldDef, BrokerAdminTypeDef.setFieldDef, and BrokerAdminTypeDef.setFieldType

getScopeTypeName

String getScopeTypeName()

Returns this event type's scope name.

field_name If set to null or contains a null string, all of the fields at the top level of the event definition will be returned. Otherwise, this should be set to the name of a structure field.





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







See:

BrokerAdminTypeDef.getBaseTypeName, BrokerAdminTypeDef.getTypeName, and BrokerAdminTypeDef.setTypeName

getStorageType

int getStorageType() throws BrokerException

Returns the storage type for the event as one of the values described in the table in BrokerAdminTypeDef.

See Also:

BrokerAdminTypeDef.setStorageType

getTimeToLive

int getTimeToLive() throws BrokerException

Returns the number of seconds that the event type will be available after being published, before it expires and is destroyed. A value of zero indicates the event will never expire.

See Also:

BrokerAdminTypeDef.setTimeToLive

getTypeName

String getTypeName()

Returns the fully-qualified name of this event type.

See:

BrokerAdminTypeDef.getBaseTypeName, BrokerAdminTypeDef.getFieldDef, and BrokerAdminTypeDef.setTypeName

hasBeenModified

boolean hasBeenModified()

Returns true if this event type has been modified. Otherwise, false is returned.


BrokerInvalidTypeException The type of this object is not FIELD_TYPE_EVENT.


BrokerInvalidTypeException The type of this object is not FIELD_TYPE_EVENT.



See:

BrokerAdminTypeDef.clearModificationFlag, and BrokerAdminTypeDef.setModificationFlag

insertFieldDef

void insertFieldDef( String field_name, int index, BrokerAdminTypeDef field_def) throws BrokerException

Inserts a new event field with the specified field_name and definition. If the field currently exists, its position and definition are updated.

Note: For information on event field name restrictions, see the webMethods Broker Client Java API Programmer’s Guide.

Specifying an index of 0 will position the field at the top of the list of event fields. Specifying an index greater than the number of event fields will position the field at the end of the list.

If field_name is null or contains a null string, this method will operate on this object.

See Also:

BrokerAdminTypeDef.getFieldDef and BrokerAdminTypeDef.setFieldDef

isSystemDefined

boolean isSystemDefined()

field_name The name of the field to be added or moved.

index The offset within the event where the field is to be positioned. The field will be inserted before the field with the specified index.

field_def The type definition for the field being added or moved.




BrokerInvalidTypeException The field's type is not FIELD_TYPE_EVENT or FIELD_TYPE_STRUCT.

BrokerNullParameterException The field_def parameter is null.

BrokerOutOfRangeException The index is less than zero.



Returns true if this event type is a system-defined type, otherwise false is returned.

Note: Only the infoset for system-defined event types may be altered. Other properties associated with system-defined event types; such as type definition, storage type, and time-to-live; may not be changed.

orderFields

void orderFields( String field_name, String new_field_names[]) throws BrokerException

Sets the order of the fields contained in field_name to the order specified in new_field_names. Any fields which are not in the new_field_names list are left in their current position, following the re-ordered fields.

See Also:

BrokerAdminTypeDef.getFieldNames

renameField

void renameField( String old_field_name, String new_field_name) throws BrokerException

field_name The name of the field whose fields are to be reordered. If set to null or to a null string, the top level of the event type definition is manipulated.

new_field_names An array of field names, specified in the order in which they are to appear in the field.


BrokerFieldNotFoundException The specified field_name or any of the entries in new_field_names does not exist in the event.



BrokerInvalidTypeException The field's type is not FIELD_TYPE_EVENT or FIELD_TYPE_STRUCT.

BrokerNullParameterException The new_field_names parameter is null or one of its entries is null.

old_field_name The name of a field to be renamed.



Renames the administrative type definition field specified by old_field_name to new_field_name. See the webMethods Broker Client Java API Programmer’s Guide for complete information on specifying field names.


See Also:

BrokerAdminTypeDef.clearField and BrokerAdminTypeDef.clearFields

setDescription

void setDescription( String description) throws BrokerException

Sets the description for the event type definition.

See Also:

BrokerAdminTypeDef.getDescription

new_field_name The new field name.


BrokerFieldNotFoundException The specified old_field_name does not exist in the event.

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

BrokerInvalidFieldNameException The old_field_name or new_field_name is invalid.

BrokerInvalidTypeException The old_field_name or new_field_name parameter does not refer to a named field. For example, a subscripted field like x[0] is not considered a named field.

BrokerNullParameterException The old_field_name or new_field_name parameter is null.

description The description to set for the event type definition.


BrokerInvalidTypeException This object's type is not FIELD_TYPE_EVENT.




setFieldDef

void setFieldDef( String field_name, BrokerAdminTypeDef field_def) throws BrokerException

Sets the type definition of the specified field_name. If the specified field does not exist, it will be created.


See Also:

BrokerAdminTypeDef.getFieldDef, BrokerAdminTypeDef.orderFields, and BrokerAdminTypeDef.setFieldType

setFieldType

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

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

field_name The name of the field whose definition is being set.

field_def The new type definition for the field.




BrokerNullParameterException The field_name or field_def parameter is null.

field_name The name of the field whose definition is being set.

field_type The field's type, defined as one of the values shown in the table in BrokerAdminTypeDef.

type_name Currently not used and should be set to null.





See Also:

BrokerAdminTypeDef.getFieldDef, BrokerAdminTypeDef.getFieldType, and BrokerAdminTypeDef.setFieldDef

setModificationFlag

void setModificationFlag()

Sets the modification flag for the type definition to true.

See:

BrokerAdminTypeDef.clearModificationFlag and BrokerAdminTypeDef.hasBeenModified

setStorageType

void setStorageType( int storage_type) throws BrokerException

Sets the storage type for the event type definition.

See Also:

BrokerAdminTypeDef.getStorageType

setTimeToLive

void setTimeToLive( int time_to_live) throws BrokerException


BrokerInvalidTypeException An attempt was made to change a field's type to FIELD_TYPE_SEQUENCE.

BrokerNullParameterException The field_name parameter is null.

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

BrokerTypeDef.STORAGE_GUARANTEED

BrokerTypeDef.STORAGE_VOLATILE


BrokerInvalidTypeException This object's type is invalid.

BrokerOutOfRangeException The storage_type parameter is invalid.




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

See Also:

BrokerAdminTypeDef.getTimeToLive

setTypeName

void setTypeName( String type_name) throws BrokerException

Sets the fully-qualified name for the event type.


See Also:

BrokerAdminTypeDef.getTypeName.

toString

String toString()

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

time_to_live The number of seconds after an event is published before it expires. A value of 0 denotes the event will never expire.


BrokerInvalidTypeException This object's type not FIELD_TYPE_EVENT.

BrokerOutOfRangeException The time_to_live parameter is less than zero.

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


BrokerInvalidEventTypeNameException This object's type not FIELD_TYPE_EVENT.

BrokerInvalidTypeException The type is not FIELD_TYPE_STRUCT or FIELD_TYPE_EVENT

BrokerNullParameterException The type_name parameter is null.



toString

String toString( int indent_level

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

BrokerAuthInfo

class BrokerAuthInfo extends java.lang.Object

This class represents the authentication information for a client session.

If the client session uses basic authentication protocol, this class contains the username and authenticator alias information. If the client session uses SSL protocol, this class contains the distinguished name of the client and the distinguished name of the authenticator.

Variables

username

String username

For basic authentication protocol, contains the client’s basic authentication username. For SSL protocol, contains the client’s distinguished name.

authenticator

String authenticator

For basic authentication protocol, contains the authenticator alias. For SSL protocol, contains the issuer’s distinguished name.

Constructors

BrokerAuthInfo

BrokerAuthInfo()

Creates an empty BrokerAuthInfo object.

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



BrokerAuthInfo

BrokerAuthInfo( String username, String authenticator)

Creates a BrokerAuthInfo object, initialized with the specified parameters.

BrokerAuthInfo

public BrokerAuthInfo( final BrokerAuthInfo source)

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

Methods

getAuthenticator

public String getAuthenticator()

Returns the client program’s authenticator alias for a basic authentication connection, or returns the issuer’s distinguished name for an SSL connection.

getUserName

public String getUserName()

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

setAuthenticator

public void setAuthenticator( final String authenticator)

Sets the client program’s authenticator alias for a basic authentication connection, or sets the issuer’s distinguished name for an SSL connection.

setUserName

public void setUserName( final String userName)

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

username The Broker client’s username or distinguished name.

authenticator The authenticator alias or the issuer’s distinguished name.

source An existing instance of the BrokerAuthInfo object.



toString

String toString()

Returns a human-readable string that contains the authentication information.

toString

String toString( int indent_level)

Returns a human-readable string that contains the authentication information. See also BrokerClientSession.auth_info.

BrokerChangeLockInfo

class BrokerChangeLockInfo

This class represents the information about a lock held by an administrative client for a Broker.

Variables

acquired

boolean acquired

Indicates whether or not this client has successfully acquired a lock for its Broker.

client_id

String client_id

If acquired is set to 0 (false), this variable will contain the identifier of the client that currently holds the lock for the Broker. If acquired is 1 (true), this variable will be set to null.

session_id

int session_id

If acquired is set to 0 (false), this variable will contain the session identifier of the client that currently holds the lock for the Broker. If acquired is 1 (true), this variable will be set to zero.

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



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.


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



Contains the client group's required encryption level as one of the BrokerConnectionDescriptor.ENCRYPT_LEVEL_* values, described in the webMethods Broker Client Java API Programmer’s Guide.

storage_type

int storage_type

Represents the client group's queue storage type using one of the BrokerTypeDef storage values, described in the table in BrokerAdminTypeDef.

Constructors


BrokerClientGroupInfo()

Creates an empty client group information object.


BrokerClientGroupInfo( String new_name, String new_description, int new_life_cycle, int new_storage_type)

Creates a BrokerClientGroupInfo object, initialized with the specified name, description, life-cycle, and event queue storage type.

Note: For information on client group name restrictions, see the webMethods Broker Client Java API Programmer’s Guide.

new_name The name for the client group.

new_description The client group's description.

new_life_cycle The life cycle of Broker clients that belong to this group. This must be one of these BrokerAdminClient lifecycle values as described in “Constants” on page 180.

new_storage_type The storage type of the event queue for clients associated with the group. Must be one of BrokerTypeDef storage values as described in the table in BrokerAdminTypeDef.



Methods

toString

String toString()

Returns a human-readable string that contains the client group information.

toString


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




If set to true, the Broker client can share its state, including its event queue. The maximum number of sharing clients is defined by the variable state_share_limit. If set to false, no other Broker client may use this client's identifier or share its state.

client_group

String client_group

Contains the name of the client group to which the Broker client belongs.

client_id

String client_id

Contains the Broker client's identifier.

high_pub_seqn

int high_pub_seqn

The highest publish sequence number that has been used by the client.

sessions

BrokerClientSession sessions[]

An array of BrokerClientSession objects describes the Broker client's currently connected sessions.

shared_event_ordering

String shared_event_ordering

The event ordering mode that will be applied to shared state clients. Valid values are BrokerConnectionDescriptor.SHARED_ORDER_*, described in the webMethods Broker Client Java API Programmer’s Guide.

state_share_limit

int state_share_limit

Defines the maximum number of Broker clients that may share state with this Broker client. If set to -1, there is no limit. This variable will be set to 1 if can_share_state is false. Otherwise this variable should contain a positive number.

user_name

String user_name

Contains the name of the owner using the Broker client.



Constructors

BrokerClientInfo

BrokerClientInfo()

Creates an empty client information object.

BrokerClientInfo

BrokerClientInfo( String new_client_id, String new_client_group, String new_app_name, boolean new_can_share_state, int new_state_share_limit, long new_high_pub_seqn)

Creates a BrokerClientInfo object, initialized with the specified client id, client group, application name, state sharing indicator, and state sharing limit.

Methods

toCompleteString

String toCompleteString()

Returns a human-readable string containing the client information, including all session information.

toString

String toString()

new_client_id The Broker client's identifier.

new_client_group The client group with which the Broker client is associated.

new_app_name The Broker client's application name.

new_can_share_state If true, this indicates the Broker client can share its state, including its event queue, with the number of Broker clients defined in new_state_share_limit. If false, other Broker clients may not use this client's identifier or share its state.

new_state_share_limit The number of Broker clients that may share this client's state. You can set a value of -1 to indicate there is no limit. Otherwise this parameter should contain a positive value.

new_high_pub_seqn The highest publish sequence number for this client. Should be set to zero or a positive number.



Returns a human-readable string containing the client information. The string does not contain any session information.

toString


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.




closeQueueBrowser

BrokerClientQueueBrowserInfo getBrowserInfo() throws BrokerException

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

getBrowserInfo

BrokerClientQueueBrowserInfo getBrowserInfo() throws BrokerException

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

getFilters

void getFilters() throws BrokerException

Returns the filters set on the queue browser.


BrokerTimeoutException The timeout is reached before any events arrive.

BrokerOutOfRangeException The max_events or msecs parameter is less than zero.

BrokerClientQueueBrowserException The queue browser is invalid.

BrokerClientQueueBrowserException The event at the last cursor position was removed. Reset the cursor to a valid position before attempting a browse operation.

BrokerClientQueueBrowserException The client queue is busy; retry the operation later.









resetFilters

void resetFilters() throws BrokerException

Removes the filters set on the queue browser. Any subsequent browse requests would consider all the events in the queue.

setFilter

void setFilter( BrokerFilterDescriptor filter) throws BrokerException

Sets the filter for queue browser's browse operation. Any subsequent browse requests would return only those events that satisfy the filter condition. If a filter for the specified document type already exists on the queue browser, it will be overwritten with the new filter setting.

setFilters

void setFilters( BrokerFilterDescriptor filters) throws BrokerException

Sets filters for queue browser's browse operation. Any subsequent browse requests would return only those events that satisfy the filter condition. If a filter for the specified document type already exists on the queue browser, it will be overwritten with the new filter setting.





BrokerFilterParseException An error occurred while parsing the filter expression

BrokerInvalidFilterException The specified filter expression on the filter object is invalid.

BrokerNullParameterException The filter parameter is null or the filter expression on the BrokerFilterDescriptor is null.

BrokerUnknownEventTypeException The specified event type on the filter object does not exist on the Broker.





setPosition

void setPosition( int position) throws BrokerException

Set the browser's cursor position to the specified position on the queue, where a value of '0' represents the head of the queue and a value of "queue length minus one" represents the end of the queue. Valid position values are in the range of 0 and "queue length-1".

BrokerClientQueueBrowserInfo

See Also:

BrokerQueueBrowser

class BrokerClientQueueBrowserInfo extends java.lang.Object

This class holds detailed information of a client queue browser.

Variables

clientId

String clientId

Client ID of the queue that is being browsed.

browserId

String browserId



BrokerNullParameterException The filters parameter is null or the filter expression on the BrokerFilterDescriptor is null.



BrokerClientQueueBrowserException The queue browser is invalid or the specified queue position is out of bounds: the position is less than zero or the position is greater than/equal to the queue length.




Client ID of the client that is browsing the queue.

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

Create an empty browser info object.


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.



Variables

auth_info

BrokerAuthInfo auth_info

The authentication information for the session. See also BrokerAuthInfo on page 315.

auth_protocol

String auth_protocol

The authorization protocol for this session.

auth_version

String auth_verison

If auth_protocol is set, the authentication protocol version for the session.

connect_time

BrokerDate connect_time

Contains the time that the Broker client connected to the Broker. This may differ from the create_time if the connection is shared with other clients in the application.

connection_id

int connection_id

Contains the Broker client's connection identifier.

create_time

BrokerDate create_time

Contains the date and time the Broker client's session was created.

encrypt_level

String encrypt_level

The encryption level for the session, if encrypt_protocol is set.

encrypt_protocol

String encrypt_protocol

The encryption protocol to use for the session, defined as one of the BrokerConnectionDescriptor.ENCRYPT_LEVEL_* values described in the webMethods Broker Client Java API Programmer’s Guide.



encrypt_version

String encrypt_version

The encryption protocol for the session, if encrypt_protocol is set.

ip_address

int ip_address

Contains the IP address of the Broker client's host.

last_activity_time

BrokerDate last_activity_time

Contains the last time that data was sent over the Broker client's connection with the Broker.

platform_info

Hashtable platform_info

Contains the Broker client's platform information, which describes the operating system and version, the hardware platform, and the version of the webMethods Broker API the client is using. See the webMethods Broker Client Java API Programmer’s Guide for a complete discussion of platform information.

port

int port

Contains the port number used by Broker client.

session_id

int session_id

Contains the Broker client's session identifier.

ssl_certificate

BrokerSSLCertificate ssl_distinguished_name

Contains the SSL certificate, if encrypt_protocol is SSL.

Constructors

BrokerClientSession

BrokerClientSession()



Creates an empty client session object.

BrokerClientSession

BrokerClientSession( int new_session_id, int new_connection_id, int new_ip_address, int new_port, boolean new_encrypt_protocol, boolean new_encrypt_version, String new_auth_protocol, String new_auth_version, BrokerSSLCertificate new_ssl_certificate, BrokerDate new_connect_time, BrokerDate new_create_time, BrokerDate new_last_activity_time)

Creates a BrokerClientSession object, initialized with the specified parameters.

Methods

toString

String toString()

Returns a human-readable string containing the client session information.

new_session_id The Broker client's identifier.

new_connection_id The Broker client connection identifier.

new_ip_address The Broker client's IP address.

new_port The port number for the session.

new_encrypt_protocol The encryption protocol for the session.

new_encrypt_version The encryption version for the session.

new_encyrpt_level The level of encryption for the session.

new_auth_protocol The authentication protocol for the session.

new_auth_version The authentication version for the session.

BrokerSSLCentificate The SSL certificate for the session.

new_connect_time The time the client connected to the Broker.

new_create_time The time the client session was created.

new_last_activity_time The time data was last sent across the connection between the client and the Broker.



BrokerClusterGatewayInfo

class BrokerClusterGatewayInfo extends java.lang.Object

This class is used to store configuration about a cluster gateway. A gateway connects two distinct clusters so that Broker clients in one cluster can subscribe to and publish events to clients in the other cluster. The gateway consists of two Brokers, each representing a distinct cluster.

See Chapter 8, “Managing Broker Clusters” for more information on clusters.

Variables

accessible_clusters

String accessible_clusters[]

The list of clusters that are accessible through this gateway.

auth_type

int auth_type

The type of authentication used by the gateway. For information about the BrokerAdminClient.AUTH_TYPE_* values for this variable, see “Constants” on page 180.

encrypt_level

int encrpyt_level

The level of encryption required by the gateway. Valid values are BrokerConnectionDescriptor.ENCRYPT_LEVEL_* values are described in the webMethods Broker Client Java API Programmer’s Guide.

gateway_broker_name

String gateway_broker_name

The name of the Broker that is the gateway for this cluster.

gateway_host_name

String gateway_host_name

The host on which the gateway Broker is running.

is_complete

boolean is_complete



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.



toString

String toString( int indent_level, boolean hide_gateway_broker, boolean hide_accessible_clusters)

Returns a string containing the cluster gateway information.

BrokerClusterInfo

class BrokerClusterInfo extends java.lang.Object

This class is used to store configuration about a group of Brokers that make up a cluster.

See Chapter 8, “Managing Broker Clusters” for more information on clusters.

Variables

auth_type

int auth_type

The type of authentication used by the cluster. For information about the BrokerAdminClient.AUTH_TYPE_* values for this variable, see “Constants” on page 180.

cluster_name

String cluster_name

The name of the cluster.

encrypt_level

int encrpyt_level


isLocalPublish

boolean isLocalPublish


hide_gateway_broker If set to true, the gateway Broker's host and name as well as the is_local information, will be omitted.

hide_accessible_clusters If set to true, the accessible_clusters and is_complete information will be omitted.



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


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.




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

Creates an empty BrokerCompleteBroker object.




BrokerCompleteBroker( BrokerInfo info)

Creates a BrokerCompleteBroker object and initializes it from a BrokerInfo object.

Methods

deepRefresh

void deepRefresh( BrokerAdminClient client) throws BrokerException

Refreshes this object's Broker information, based on the specified administrative Broker client. The client_groups and event_types data members will be updated using the BrokerCompleteClientGroup.retrieve and BrokerCompleteEventType.retrieve methods.

Any client groups or event types which no longer exist, or which this client does not have permission to read, will be removed from this object.

Note: The is_default data member will be updated if, and only if, this object was created using the BrokerCompleteServer.deepRefresh method.

See Also:

BrokerCompleteBroker.refresh

deepRetrieve

static BrokerCompleteBroker deepRetrieve( BrokerAdminClient client) throws BrokerException

info The BrokerInfo object used to initialize this object.

client The administrative client to be used to refresh this object.



BrokerNullParameterException The client parameter is null.

client The administrative client to be used to retrieve the Broker information.



Returns a BrokerCompleteBroker object containing information on the Broker to which the administrative Broker client is connected. All client groups and event types which this client has permission to access will be set in the data members client_groups and event_types data members, using the BrokerCompleteClientGroup.retrieve and BrokerCompleteEventType.retrieve methods.

Note: The is_default data member will be set if, and only if, this object was created using the BrokerCompleteServer.deepRefresh method.

See Also:

BrokerCompleteBroker.retrieve

deepStore

void deepStore( BrokerAdminClient client) throws BrokerException

Stores the information from this object into the Broker to which the client is connected.

The broker_name, brokers_in_territory, is_default, and territory_name data members are ignored. If the description has been set, it replaces the Broker's existing description.

The information contained in the client_groups and event_types data members are stored using the BrokerCompleteClientGroup.store and BrokerCompleteEventType.store methods.

If an exception is thrown, none of the Broker's information will be modified.




client The administrative client to be used to store the Broker information.



BrokerInvalidClientGroupNameException Specified client group name is not valid.

BrokerNoPermissionException The client does not have permission to change the Broker's configuration.


BrokerOutOfRangeException A client group contained an invalid value for its life cycle or storage parameter type.



See Also:

BrokerCompleteBroker.store

refresh

void refresh( BrokerAdminClient client) throws BrokerException

Refreshes this object's Broker information, based on the specified administrative Broker client. The client_groups and event_types data members are not updated.

Note: The is_default data member will be updated if, and only if, this object was created using the BrokerCompleteServer.deepRefresh method.

See Also:

BrokerCompleteBroker.deepRefresh

retrieve

static BrokerCompleteBroker retrieve( BrokerAdminClient client) throws BrokerException

Returns a BrokerCompleteBroker object containing information on the Broker to which the administrative Broker client is connected.

The default Broker status will be set only if this BrokerCompleteBroker object was created by a BrokerCompleteServer or BrokerCompleteCollection method.

No client group or event type information is retrieved.

BrokerUnknownEventTypeException A client group contains an event type in its can_publish or can_subscribe list that does not exist on the Broker.





client The administrative client to be used to retrieve contents for this object.




See Also:

BrokerCompleteBroker.deepRetrieve

store


Stores most of the information from this object into the Broker to which the client is connected. The broker_name, brokers_in_territory, is_default, and territory_name are not stored into the Broker.

If an exception is thrown, none of the Broker's information will be modified.

See Also:

BrokerCompleteBroker.deepStore

toString

String toString()

Converts the information contained in this object into a string in ADL format that may be saved to a file. For more information on ADL, see Administering webMethods Broker.

Returns an empty string if all of the data members are null or if their conversion results in an empty string.











toString

String toString( int indent_level) throws BrokerException



write

void write( Writer writer, int indent_level) throws BrokerException, IOException

Writes out this object's Broker information in ADL format, usually to a file. No data will be written if the broker_name is null.

For more information on ADL, see Administering webMethods Broker.

BrokerCompleteClient

class BrokerCompleteClient extends java.lang.Object

This class represents all configuration information about a Broker client and is used to load, save, import or export the client's configuration.



BrokerOutOfRangeException The indent_level parameter is less than 0.

writer The file where the data is to be written.



IOException There was an error writing the data to the file.

BrokerNullParameterException The writer parameter is null.




Variables

client_info

BrokerClientInfo client_info

Contains the Broker client's information. See BrokerClientInfo for more information.

infoset

BrokerEvent infoset

Contains the Broker client's infoset. See the webMethods Broker Client Java API Programmer’s Guide for more information on client infosets.

replace_subscriptions_on_store

boolean replace_subscriptions_on_store

If set to true, all of the Broker client's event subscriptions will be replaced when the store method is invoked.

subscriptions

BrokerSubscription subscriptions[]

Contains the Broker client's list of event subscriptions.

Constructors


BrokerCompleteClient()

Creates an empty BrokerCompleteClient object.


BrokerCompleteClient( BrokerClientInfo info)

This is a copy constructor.

info The object being copied.



Methods

refresh


Refreshes this object's Broker information, based on the specified administrative Broker client. The client_info.client_id variable must be set to the client id for client.

See Also:

BrokerCompleteClient.retrieve

retrieve

static BrokerCompleteBroker retrieve( BrokerAdminClient client) throws BrokerException

Returns a BrokerCompleteClient object containing information on the specified client.





BrokerNoPermissionException The client does not have permission to browse the information.

BrokerUnknownClientIdException The client ID specified in the client_info.client_id variable does not exist on the Broker.





BrokerNoPermissionException The client does not have permission to browse the information.



See Also:

BrokerCompleteClient.refresh

store


Stores most of the information from this object for the Broker client. If the client is not a member of a Client Group with an explicit-destroy life cycle, calling this method will have no effect.

If the Broker client does not exist on the Broker, it will be created and initialized with the information is set in this object.

If the Broker client does exist, then some information is overwritten and some information merged with the existing settings as follows:

The app_name, client_group, high_pub_seqn, can_share_state, user_name and authenticator_name fields in the client_info object are ignored if the client already exists. These values are only set when creating the Broker client.

The access_label field in the client_info object is always ignored.

If the state_share_limit in the client_info object is non-zero and the can_share_state flag is true in an existing or new client, the state_share_limit will be set with the new value.

If the subscriptions list is set, its content will be merged with any existing subscriptions. If the replace_subscriptions_on_store flag is true, this list of subscriptions will replace the previous list.

If the infoset is set, it replaces the existing client infoset.

If an exception is thrown, none of the Broker client's information will be modified.

BrokerUnknownClientIdException The client id specified in the client_info.client_id variable does not exist on the Broker.




BrokerInvalidSubscriptionException The filter string in a subscription in the subscriptions variable contains a parse error.




See Also:

BrokerCompleteClient.retrieve

toString

String toString()



See:

BrokerCompleteClient.write

toString






BrokerOutOfRangeException A sub_id element in a subscription contained in subscriptions is less than zero or the state_share_limit element is less than -1.

BrokerUnknownClientGroupException The client group in the client_info.client_group variable does not exist on the Broker.

BrokerUnknownEventTypeException The event type name listed in one of the subscriptions does not exist on the Broker. All other subscriptions are still created if this exception is thrown.





See Also:

BrokerCompleteClient.write.

write


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.


See Also:

BrokerCompleteClient.toString.

BrokerCompleteClientGroupclass BrokerCompleteClientGroup extends java.lang.Object

This class represents all configuration information about a client group and is used to load, save, import or export the group's configuration.

Variables

acl

BrokerAccessControlList acl

Contains the distinguished names of entities which may create clients in this group. See BrokerServerClient for details.











can_publish

String can_publish[]

Contains an array of event type names which can be published by clients in this group.

can_subscribe

String can_subscribe[]

Contains an array of event type names to which client's in this group can subscribe.

client_group_info

BrokerClientGroupInfo client_group_info

Contains information about this client group. See BrokerClientGroupInfo for details.

ignore_change_errors_on_store

boolean ignore_change_errors_on_store

If set to true, this flag disables any permission exceptions that otherwise might occur when you try use the store method.

replace_lists_on_store

boolean replace_lists_on_store

If set to true, any event types that exist in the Broker's can-publish and can-subscribe lists for this client group, but which are not specified by this object will be deleted when this object's store method is invoked. If replace_infosets_on_store is false, pre-existing event types on the Broker will not be deleted when the store method is invoked.

Constructors

BrokerCompleteClientGroup

BrokerCompleteClientGroup()

Creates an empty BrokerCompleteClientGroup object.

BrokerCompleteClientGroup

BrokerCompleteClientGroup( BrokerClientGroupInfo info)

Creates a BrokerCompleteBroker object and initializes it from a BrokerClientGroupInfo object.

info The BrokerInfo object used to initialize this object.



Methods

refresh


Refreshes this object's client group information, using the specified administrative Broker client. The client_group_info.name data member must be set to the name of the desired client group name.

If the access control list cannot be accessed, the acl member will be set to null.

See Also:

BrokerCompleteClientGroup.retrieve

retrieve

static BrokerCompleteClientGroup retrieve( BrokerAdminClient client, String client_group_name) throws BrokerException

Retrieves the information about a specified client group, using the specified administrative client.





BrokerNoPermissionException The client does not have permission to read the client group configuration.

BrokerNullParameterException The client parameter, the data member client_group_info, or the variable client_group_info.name is null.

BrokerUnknownClientGroupException The client group does not exist on the Broker.


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




See Also:

BrokerCompleteClientGroup.refresh

store

void store( BrokerAdminClient client) throws BrokerException

Store this object's client group information into the Broker to which the specified administrative Broker client is connected.

If the client group does not exist, it is created and initialized from this object.

If the client group already exists, the following rules apply:

If the description data member is set in this object, it will replace the existing client group description on the Broker.

If the can_publish and can_subscribe lists are set, their contents are merged with those for the client group on the Broker.

If the acl data member is set, it replaces the existing one for the client group on the Broker.

The life cycle and storage type properties are not changed for the client group on the Broker.





BrokerNullParameterException The client or client_group_name parameter is null.

BrokerUnknownClientGroupException The client_group_name does not exist on the Broker.

client The administrative client to be used to store this object.





See Also:

BrokerCompleteClientGroup.refreshand BrokerCompleteClientGroup.retrieve

toString

String toString()



toString


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




BrokerNullParameterException The client parameter, the data member client_group_info, or the variable client_group_info.name is null.l








Writes out this object's Broker information in ADL format, usually to a file. No data will be written if the client_group_info member is null. For more information on ADL, see Administering webMethods Broker.

BrokerCompleteCollectionclass BrokerCompleteCollection extends java.lang.Object

This class is used as a container to collect various Broker objects. It is commonly used to create an export file containing a Broker Server's configuration or to hold the results of an imported configuration file.

Note that several of the objects in this collection are also container objects. Including an object in one of those collection objects can result in that object being placed in an export file or used during an import operation.

Variables

acls

BrokerAccessControlList acls[]

Contains all of the access control lists for this collection.

brokers

BrokerCompleteBroker brokers[]

Contains all the Broker Servers in this collection.

client_groups

BrokerCompleteClientGroup client_groups[]

Contains all of the client groups in this collection.

clients

BrokerCompleteClient clients[]

Contains all of the client groups in this collection.







event_types

BrokerCompleteEventType event_types[]

Contains all of the event type definitions for this collection.

servers

BrokerCompleteServer servers[]

Contains all the server definitions in this configuration.

Constructors

BrokerCompleteCollection

BrokerCompleteCollection()

Creates an empty BrokerCompleteCollection object.

Methods

read

static BrokerCompleteCollection read( Reader reader) throws BrokerException, IOException

Creates a new BrokerCompleteCollection object from the text supplied from reader. The input is usually read from a file. The reader can only be read from once. Unlike the readFile method, this method does not support the file formats used in earlier releases of webMethods Broker.

For greater efficiency, do not pass a BufferedReader because the underlying parser already performs read buffering.

See Also:

BrokerCompleteCollection.readFile

reader The file from which the configuration is to be created.


IOException There was an error reading data from the file.

BrokerInputParseException There was a parse error in the input data.

BrokerNullParameterException The reader parameter is null.



readFile

static BrokerCompleteCollection readFile( String filename) throws BrokerException, IOException

Creates a new BrokerCompleteCollection object from the text supplied from the file with the specified filename.

If the file does not use the most current file format, an attempt will be made to re-read the file using a file format from previous webMethods Broker release.

See Also:

BrokerCompleteCollection.readFile

toString

String toString()



toString




reader The file from which the configuration is to be created.


IOException There was an error reading data from the file.

BrokerInputParseException There was a parse error in the input data.

BrokerNullParameterException The filename parameter is null.




write


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.


You can call this method repeatedly with the same Writer to write multiple collections into a single file.

This method does not write the export file format version number to the file. Invoke the writeVersionNumber method once before invoking this method to write the version number to the beginning of the file.

See Also:

BrokerCompleteCollection.writeVersionNumber

writeVersionNumber

static void writeVersionNumber( Writer writer, int indent_level) throws BrokerException, IOException

Writes out this object's version, usually to a file. This method is usually invoked before invoking the write method of this class, or any other BrokerComplete* class, so that the version number appears before the configuration information.The inclusion of the file format version at the top of the exported file is not mandatory.







writer The file where the version number is to be written.




The writing of the version number was separated from the BrokerComplete*.write methods so that you may control which parts of a collection are written to the file and write the version number only once, at the top of the file.

See Also:

BrokerCompleteBroker.write, BrokerCompleteClientGroup.write, BrokerCompleteEventType.write, and BrokerCompleteServer.write

BrokerCompleteEventTypeclass BrokerCompleteEventType extends java.lang.Object

This class represents all configuration information for a event type and is used to load, save, import or export a Broker's configuration.

Variables

infosets

BrokerEvent infosets[]

Contains all the infosets for this event type.

replace_infosets_on_store

boolean replace_infosets_on_store

If set to true, any infosets that exist on the Broker but are not specified by this object will be deleted when this object's store method is invoked. If replace_infosets_on_store is false, pre-existing infosets on the Broker will not be deleted when the store method is invoked.

type_def

BrokerAdminTypeDef type_def

Contains the event type definition.







Constructors

BrokerCompleteEventType

BrokerCompleteEventType()

Creates an empty BrokerCompleteEventType object.

BrokerCompleteEventType

BrokerCompleteEventType(BrokerAdminTypeDef type_def

Creates a BrokerCompleteEventType object, initialized from the specified administrative type definition object.

Methods

refresh


Refreshes this object's event type information, using the specified administrative Broker client. The data member type_def must be set.

See Also:

BrokerCompleteEventType.retrieve

type_def The BrokerAdminTypeDef used to initialize this object.




BrokerNoPermissionException The client does not have permission to read the event type configuration.

BrokerNullParameterException The client parameter or the data member type_def is null, or the type_def has a null event type name.

BrokerUnknownEventTypeException The event type contained in the object specified by type_def not exist on the Broker.



retrieve

static BrokerCompleteEventType retrieve( BrokerAdminClient client, String event_type_name) throws BrokerException

Retrieves the information about a specified event type, using the specified administrative client.

See Also:

BrokerCompleteEventType.refresh

store


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.


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



BrokerNoPermissionException The client does not have permission to read the event type configuration.

BrokerNullParameterException The client or event_type_name parameter is null.





If replace_infosets_on_store is true, any infosets that exist on the Broker but are not specified by this object will be deleted. If replace_infosets_on_store is false, pre-existing infosets on the Broker will not be deleted.

If an exception is thrown, the Broker will not have been updated.

See Also:

BrokerCompleteEventType.refresh and BrokerCompleteEventType.retrieve

toString

String toString()

Converts the event type information contained in this object into a string in ADL format that may be saved to a file. For more information on ADL, see Administering webMethods Broker.

toString


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.





BrokerNullParameterException The client parameter, the data member client_group_info, or the variable client_group_info.name is null.l





write


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.


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


Contains the access control list for this Broker Server.

brokers

BrokerCompleteBroker brokers[]

Contains the Broker Servers' names.

description

String description










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,



String app_name, BrokerConnectionDescriptor desc) throws BrokerException

Refreshes this object's Broker Server information, based on the specified administrative Broker client. All of this object's data members will be updated.

Any Brokers which no longer exist, or for which the client does not have permission to read, will be removed from the brokers array. The information for each Broker in the array will be refreshed using the BrokerCompleteBroker.deepRefresh method.

The client_id, client_group, app_name, and desc are all used to establish individual connections to each Broker in the brokers array. Any information that the client does not have permission to read will be set to null. For more information, see BrokerAdminClient.

See Also:

BrokerCompleteServer.refresh

deepRetrieve

static BrokerCompleteServer deepRetrieve( BrokerAdminClient client) String client_id, String client_group, String app_name, BrokerConnectionDescriptor desc) throws BrokerException











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.


See Also:

BrokerCompleteServer.retrieve

deepStore

void deepStore( BrokerAdminClient client) String client_id, String client_group, String app_name, BrokerConnectionDescriptor desc) throws BrokerException












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.


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.







See Also:

BrokerCompleteServer.store

refresh


Refreshes this object's Broker Server information, based on the specified administrative Broker client. Any host information that the client does not have permission to read will be set to null.

See Also:

BrokerCompleteServer.deepRefresh

retrieve

static BrokerCompleteServer retrieve( BrokerAdminClient client) throws BrokerException

Returns a BrokerCompleteServer object containing information on the host to which the administrative Broker client is connected. Retrieves the server information, but not information for Brokers.




BrokerNullParameterException client, client_group, or app_name parameter is null.








See Also:

BrokerCompleteServer.deepRetrieve

store


Stores the information from this object into the Broker to which the client is connected.

The host name in this object is ignored, but other values may be overwritten or merged.

If the description is set, it will replace the existing value.

If the port is set to something other than zero, it will replace the existing port number.

If the log_config is set, it will replace the existing logging configuration.

If the ssl_config is set, it will replace the existing SSL configuration.

If the acl is set, it will replace the existing access control list.

The Brokers contained in brokers will not be stored under this host. These must be stored separately by using the BrokerCompleteBroker.store or BrokerCompleteBroker.deepStore method. You may also use the BrokerCompleteServer.deepStore method to store all of the host information, including the Brokers.

If an exception is thrown, none of the host's information will be modified.

See Also:

BrokerCompleteServer.deepStore











toString

String toString()



toString




write


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.













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


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

Creates an empty BrokerCompleteTerritory object.


BrokerCompleteTerritory( BrokerTerritoryInfo info)

Creates a territory object, setting the info variable in the process.

info The territory information to set in the newly created object.



Methods

refresh


Refreshes this object's Broker territory information, based on the specified administrative Broker client. Any information that the client does not have permission to read will be set to null.

See Also:

BrokerCompleteTerritory.retrieve

retrieve

static BrokerCompleteTerritory retrieve( BrokerAdminClient client) throws BrokerException

Returns a BrokerCompleteTerritory object containing information on the host to which the administrative Broker client is connected. Retrieves the server information, but not information for Brokers.

See Also:

BrokerCompleteTerritory.store











store


Stores the territory information from this object into the Broker to which the client is connected.

If the Broker does not belong to the territory, then an attempt to locate it is made, using the other_brokers_in_territory list. If the territory cannot be found, it will be created.

If the territory already existed, then all of its information will be overwritten.

The auth_type and encrypt_level in the info member will replace the current settings in the territory.

If the access control list is set, it will replace the existing acl.

If an exception is thrown, none of the territory's information will be modified.

See Also:

BrokerCompleteTerritory.retrieve

toString

String toString()



toString


client The administrative client to be used to store the Broker territory information.




BrokerNullParameterException The client parameter is null or the variable info or info.territory_name are null





write


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.


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.













Variables

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.


BrokerCompleteTerritoryGateway( BrokerTerritoryGatewayInfo info)

Creates a territory gateway object, setting the info variable in the process.

info The gateway information to set in the newly created object.



Methods

refresh


Refreshes this object's territory gateway information, based on the specified administrative Broker client. Any information that the client does not have permission to read will be set to null.

See Also:

BrokerCompleteTerritoryGateway.retrieve

retrieve

static BrokerCompleteTerritoryGateway retrieve( BrokerAdminClient client) throws BrokerException

Returns a BrokerCompleteTerritory object containing information on the host to which the administrative Broker client is connected. Retrieves the server information, but not information for Brokers.




BrokerNotInTerritory The Broker to which client is connected is not part of a territory.

BrokerNullParameterException The client parameter is null or the variable info or info.remote_territory_name is null.





BrokerNotInTerritory The Broker to which client is connected is not part of a territory.



See Also:

BrokerCompleteTerritoryGateway.store

store


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.



client The administrative client to be used to store the Broker territory information.




See Also:

BrokerCompleteTerritoryGateway.retrieve

toString

String toString()



toString








BrokerOutOfRangeException Either the specified gateway already exists and was established by another Broker in this Broker's territory or it has a different remote Broker. If this exception is thrown, the gateway is not altered.

BrokerUnknownBrokerNameException The other half of the gateway has not been established and the remote Broker could not be found.






write


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.


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.









Constructors


BrokerFilterDescriptor()

Creates an empty filter descriptor.


BrokerFilterDescriptor( String event_type_name, String filter_expr filter)

Creates a BrokerFilterDescriptor object, setting the eventTypeName and filterExpr to the values specified.

Methods

toString

String toString()

Returns a string containing the filter in a human-readable format.

BrokerForwardQueueBrowserclass BrokerForwardQueueBrowser implements BrokerQueueBrowser

This class provides queue browsing capabilities to view events in the forwarding queue.

Methods

browseEvents


Browses the queue and returns one or more events from the forwarding queue. Returns immediately with one of the following:

event_type_name Document name

filter_expr filter Expression



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.



closeQueueBrowser

void closeQueueBrowser() throws BrokerException

Closes the current forwarding queue browser object; otherwise throws Broker exception.

getBrowserInfo

BrokerQueueBrowserInfo getBrowserInfo() throws BrokerException

Gets information about the current forwarding queue browser. Returns a BrokerQueueBrowserInfo object.

getFilters

void getFilters() throws BrokerException


BrokerTimeoutException The timeout is reached before an event arrives.


BrokerQueueBrowserException The queue browser is invalid.

BrokerQueueBrowserException The event at the last cursor position was removed. Reset the cursor to a valid position before attempting a browse operation.

BrokerQueueBrowserException The queue is busy; retry the operation later.

BrokerQueueBrowserException The queue is empty and no more events can be returned. For forwarding queues, this exception might be thrown when there are only internal events within the requested browsing range.

BrokerInvalidClientException The client has been destroyed or is disconnected.





Returns the filters set on the forwarding queue browser.

resetFilters


Removes the filters set on the queue browser. Any subsequent browse requests would consider all the events in the queue.

setFilter

void setFilter( BrokerFilterDescriptor filter) throws BrokerException

Sets the filter for queue browser's browse operation. Any subsequent browse requests would return only those events that satisfy the filter condition. If a filter for the specified document type already exists on the queue browser, it will be overwritten with the new filter setting.

setFilters

void setFilters( BrokerFilterDescriptor filters) throws BrokerException

Sets filters for forwarding queue browser's browse operation. Any subsequent browse requests would return only those events that satisfy the filter condition. If a filter for the specified document type already exists on the queue browser, it will be overwritten with the new filter setting.













setPosition


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









Contains the cluster's name.

description

String description


territory_name


Contains the Broker's name.

Constructors

BrokerInfo

BrokerInfo()

Creates a BrokerInfo object without setting the name or description.

BrokerInfo

BrokerInfo( String territory, String host, String name, String description)

Creates a BrokerInfo object, setting the territory_name, broker_host, broker_name, and description to the values specified.

Note: For information on territory and Broker name restrictions, see the webMethods Broker Client Java API Programmer’s Guide.

BrokerJoinFailureInfo

class BrokerJoinFailureInfo extends java.lang.Object

territory The Broker's territory.

host The Broker's host name.

name The Broker's name.

description The Broker's description.



This class is used to report failures from the BrokerAdminClient.joinTerritory method. It contains a list of any client groups or event types that conflicted with the territory. See “Managing Broker Territories” on page 93 for more information on territories.

Variables

client_group_names

String client_group_names[]

Contains the names of all the Broker's client groups whose definitions conflicted with the territory's definitions.

event_type_names

String event_type_names[]

Contains the names of all the Broker's event types whose definitions conflicted with the territory's definitions.

ConstructorsBrokerJoinFailure()

Creates an empty BrokerJoinFailure object.

BrokerLockedClientQueueBrowser

See Also:

BrokerLockedForwardQueueBrowser

class BrokerLockedClientQueueBrowser extends BrokerClientQueueBrowser

This class provides extended queue browsing capabilities to re-arrange the contents of a client queue.

Methods

deleteEvents

int deleteEvents( long[] seqns) throws BrokerException



Deletes events with the specified receipt sequence numbers from the client queue. Returns the number of events successfully deleted from the queue. The presence of invalid sequence numbers (zero or a value less than zero) or duplicate sequence numbers would result in an error. You can use a delete request to remove unacknowledged events from the queue.

insertEventsAtHead

void insertEventsAtHead( BrokerEvent[] events) throws BrokerException

Inserts events into the client queue at the head position (queue position of zero).

insertEventsAtTail

void insertEventsAtTail( BrokerEvent[] events) throws BrokerException



BrokerClientQueueBrowserException A receipt sequence number of value zero is specified, which is not a valid receipt sequence number.

BrokerClientQueueBrowserException The client queue is busy; retry the operation.

BrokerInvalidSequenceNumberException No event was found on the client queue for one or more of the specified receipt sequence numbers.

BrokerNullParameterException The seqns parameter is null or of array length zero.

BrokerOutOfRangeException A duplicate sequence number is found on the array.



BrokerInvalidEventException One or more of the specified event is invalid.

BrokerNoPermissionException The target client queue does not have permission to subscribe to one or more of the specified events.

BrokerNullParameterException The events parameter is null or of array length zero or one of the array element is null.



Inserts events into the client queue at the tail position (queue position "queue length minus one").

modifyEvents

int modifyEvents( long[] seqns) throws BrokerException

Modifies events in the queue. Events with the specified receipt sequence numbers in the client queue will be replaced with the specified events. The presence of invalid sequence numbers (zero or a value less than zero) or duplicate sequence numbers would result in an error. Any attempt to modify an event that is unacknowledged would also result in an error. Note that the storage type of the replaced and replacing events should match; any mismatch would be raised as an exception.




BrokerNoPermissionException The target client does not have permission to subscribe to one or more of the specified events.




BrokerClientQueueBrowserException A receipt sequence number of value zero is specified, which is not a valid receipt sequence number.

BrokerClientQueueBrowserException The client queue is busy; retry the operation.

BrokerClientQueueBrowserException The storage types of replaced and replacing events do not match.

BrokerClientQueueBrowserException The event cannot be modified as it has already been retrieved by the client session and is not yet acknowledged, i.e., the event is an "unacknowledged" event.


BrokerNullParameterException The seqns or the events parameter is null or of array length zero.



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


Deletes regular events with the specified receipt sequence numbers from the forwarding queue. Returns the number of events successfully deleted from the forwarding queue. The presence of invalid sequence numbers (zero or a value less than zero) or duplicate sequence numbers would result in an error. You can use a delete request to remove unacknowledged events from the queue.

BrokerOutOfRangeException A duplicate sequence number is found on the array



BrokerQueueBrowserException A receipt sequence number of value zero is specified, which is not a valid receipt sequence number.

BrokerQueueBrowserException The forwarding queue is busy; retry the operation.

BrokerInvalidSequenceNumberException No event was found on the forwarding queue for one or more of the specified receipt sequence numbers.






insertEventsAtTail


Inserts events into the forwarding queue at the tail position (queue position "queue length minus one").

Note: webMethods Broker Java API does not support the "insert events at head" operation although the "insertEventsAtHead" API is available to do so. Invoking the insertEventsAtHead API throws an "unsupported operation" exception.

modifyEvents

void modifyEvents( long[] seqns, BrokerEvent[] events) throws BrokerException

Modifies events in the forwarding queue. Events with the specified receipt sequence numbers in the forwarding queue will be replaced with the specified events. The presence of invalid sequence numbers (zero or a value less than zero) or duplicate sequence numbers would result in an error. Any attempt to modify an event that is unacknowledged would also result in an error. Note that the storage type of the replaced and replacing events should match; any mismatch would be raised as an exception.



BrokerInvalidEventException One or more of the specified events is invalid.





BrokerQueueBrowserException The queue is busy; retry the operation.

BrokerQueueBrowserException The storage types of replaced and replacing events do not match.

BrokerQueueBrowserException The event cannot be modified as it has already been retrieved and is not yet acknowledged, i.e., the event is an "unacknowledged" event.



BrokerLockedQueueBrowser

interface BrokerLockedQueueBrowser extends BrokerQueueBrowser

This interface provides queue browsing capabilities to view and modify the contents of a queue.

Methods

deleteEvents


Deletes events with the specified receipt sequence numbers from the queue. Returns the number of events successfully deleted from the queue. The presence of invalid sequence numbers (zero or a value less than zero) or duplicate sequence numbers would result in an error. You can use a delete request to remove unacknowledged events from the queue.

BrokerQueueBrowserException Invalid input arguments. Means that the array length of sequence number is not equal to the array length of events.

BrokerInvalidSequenceNumberException No event was found on the queue for one or more of the specified receipt sequence numbers.


BrokerOutOfRangeException A duplicate sequence number is found on the array




BrokerQueueBrowserException The client queue is busy; retry the operation.

BrokerInvalidSequenceNumberException No event was found on the queue for one or more of the specified receipt sequence numbers.




insertEventsAtHead

void insertEventsAtHead( BrokerEvent[] events) throws BrokerException

Inserts events into the client queue at the head position (queue position of zero).

insertEventsAtTail


Inserts events into the queue at the tail position (queue position "queue length minus one").






BrokerNoPermissionException The target client or remote Broker's forwarding queue does not have permission to subscribe to one or more of the specified events.


events An array of events that you want to insert into the queue.




BrokerNoPermissionException The target client does not have permission to subscribe to one or more of the specified events.





modifyEvents

void modifyEvents( long[] seqns), BrokerEvent[] events) throws BrokerException

Modifies events in the queue. Events with the specified receipt sequence numbers in the queue will be replaced with the specified events. The presence of invalid sequence numbers (zero or a value less than zero) or duplicate sequence numbers would result in an error. Any attempt to modify an event that is unacknowledged would also result in an error. Note that the storage type of the replaced and replacing events should match; any mismatch would be raised as an exception.

BrokerLogConfig

class BrokerLogConfig extends java.lang.Object

seqns An array of sequence numbers that identify the events to be modified in the queue

events An array of BrokerEvent that will be updated in place of the events in the queue.




BrokerQueueBrowserException The queue is busy; retry the operation.

BrokerQueueBrowserException The storage types of replaced and replacing events do not match.

BrokerQueueBrowserException The event cannot be modified as it has already been retrieved by the client session and is not yet acknowledged, i.e., the event is an "unacknowledged" event.






This class provides methods for configuring the log output produced by a Broker. The BrokerLogConfig supports three different levels of message logging:

In addition, the BrokerLogConfig supports any of these mechanisms for logging events:

UNIX syslog facility

Windows NT event log

SNMP alerts.

Variables

LOG_OUTPUT_NT_EVENT_LOG

LOG_OUTPUT_SNMP_TRAP

LOG_OUTPUT_UNIX_SYSLOG

LOG_TOPIC_ALERT

LOG_TOPIC_INFO

LOG_TOPIC_WARNING

Constructors

BrokerLogConfig

BrokerLogConfig()

Creates a log configuration object with all logging disabled.

BrokerLogConfig

BrokerLogConfig( BrokerLogConfig log_config) throws BrokerException

Constructor that makes a new log configuration object that is a copy of log_config.

Level Description

Alert Identifies critical messages.

Warning Identifies important messages.

Informational Identifies informational messages.

log_config The object being copied.



Methods

clearLogOutput

void clearLogOutput( String code) throws Brokerexception

Deletes one entry from the specified log output.

See Also:

BrokerLogConfig.clearLogOutputs

clearLogOutputs

void clearLogOutputs()

Deletes all entries from all log outputs.

See:

BrokerLogConfig.clearLogOutput.

clearLogTopic

void clearLogTopic( String code) throws BrokerException


BrokerNullParameterException The log_config parameter is null.

code Specifies the log output that is to be cleared. Must be one of the following values:





BrokerNullParameterException The code parameter is null.



Deletes one entry from a single log topic.

See Also:

BrokerLogConfig.clearLogTopics

clearLogTopics

void clearLogTopics()

Deletes all entries from all log topics.

See:

BrokerLogConfig.clearLogTopic

getLogOutput

BrokerLogConfigEntry getLogOutput( String code) throws BrokerException

Returns the state of the specified log output. For more information, see BrokerLogConfigEntry.

code Specifies the log topic that is to be cleared. Must be one of the following values:

LOG_TOPIC_ALERT

LOG_TOPIC_INFO

LOG_TOPIC_WARNING



code Specifies the log output whose state is to be returned. Must be one of the following values:






BrokerOutOfRangeException The code parameter is not in this log configuration.



See Also:

BrokerLogConfig.getLogOutputs, BrokerLogConfig.setLogOutput, and BrokerLogConfig.setLogOutput

getLogOutputs

BrokerLogConfigEntry[] getLogOutputs()

Returns an array of BrokerLogConfigEntry object containing the state of the each log output.

See:

BrokerLogConfig.getLogOutput, BrokerLogConfig.setLogOutput, BrokerLogConfig.setLogOutput

getLogTopic

BrokerLogConfigEntry getLogTopic( String log_topic) throws BrokerException

Returns the state of the specified log topic. See BrokerLogConfigEntry on page 394 for more information.

See Also:

BrokerLogConfig.getLogTopics and BrokerLogConfig.setLogTopic

getLogTopics

BrokerLogConfigEntry[] getLogTopics()

Returns an array of BrokerLogConfigEntry object containing the state of each log topic. See BrokerLogConfigEntry on page 394 for more information.

See:

BrokerLogConfig.getLogTopic and BrokerLogConfig.setLogTopic

log_topic Specifies the log topic whose state is to be returned. Must be one of the following values:

LOG_TOPIC_ALERT

LOG_TOPIC_WARNING

LOG_TOPIC_INFO



BrokerOutOfRangeException The code parameter is not set in this log configuration.



setLogOutput

void setLogOutput( BrokerLogConfigEntry log_output) throws BrokerException

Sets the value of a single log topic to the specified state. See BrokerLogConfigEntry on page 394 for more information.

See Also:

BrokerLogConfig.getLogOutput, BrokerLogConfig.getLogOutputs, BrokerLogConfig.setLogOutput

setLogOutput

void setLogOutput( String code, boolean enabled, String value) throws BrokerException

Sets or creates a single log output state.

See BrokerLogConfigEntry on page 394 for more information.

See Also:

BrokerLogConfig.getLogOutput, BrokerLogConfig.getLogOutputs, BrokerLogConfig.setLogOutput

log_output Specifies the type and state of log output that is to be set.


BrokerNullParameterException log_output parameter or log_output.code is null.

code Specifies the log output whose state is to be set. Must be one of the following values:




enabled If set to true, this output is enabled.

value The value to be set. Usually set to null.





setLogTopic

void setLogTopic( BrokerLogConfigEntry log_topic) throws BrokerException

Sets the value of a single log topic's state.


See Also:

BrokerLogConfig.getLogTopic, BrokerLogConfig.getLogTopics, and BrokerLogConfig.setLogTopic

setLogTopic

void setLogTopic( String code, boolean enabled, String value) throws BrokerException

Sets the value of a single log output's state.


See Also:

BrokerLogConfig.getLogTopic, BrokerLogConfig.getLogTopics, and BrokerLogConfig.setLogTopic

log_topic The log topic that is to be set.


BrokerNullParameterException log_topic parameter is null or log_topic.code is null.

code Specifies the log topic whose state is to be set. Must be one of the following values:

LOG_TOPIC_ALERT

LOG_TOPIC_WARNING

LOG_TOPIC_INFO

enabled If set to true, this topic is enabled.

value The value to be set. Usually set to null.





toString

String toString()

Returns a string containing the log configuration in a human-readable format.

toString


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.




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

Creates an empty log configuration entry.


BrokerLogConfigEntry( String new_code, boolean new_enabled, String new_value) throws BrokerException

Creates an initialized log entry.

BrokerMonitorClientpublic class BrokerMonitorClient extends java.lang.Object

This class represents a Broker Monitor client.

new_code Indicates the type of log output or log topic. Must be one of the following BrokerLogConfig values:




LOG_TOPIC_ALERT

LOG_TOPIC_INFO

LOG_TOPIC_WARNING

new_enabled If true, indicates this log output or topic is enabled. Otherwise, it is disabled.

new_value A string that is associated with the log output or topic. Usually set to null.



Constant

BROKER_MONITOR_DEFAULT_PORT

Constructors

BrokerMonitorClient

BrokerMonitorClient(String broker_monitor_host) throws BrokerException

Creates a BrokerMonitorClient object for the specified Broker Monitor host. Make sure the Broker Monitor process is running before creating the BrokerMonitorClient object.

BrokerMonitorClient

BrokerMonitorClient( String broker_monitor_host, BrokerConnectionDescriptor desc) throws BrokerException

Creates a BrokerMonitorClient object for the specified Broker Monitor host. Make sure the Broker Monitor process is running before creating the BrokerMonitorClient object.

broker_monitor_host

The Broker Monitor host for which this Broker Monitor client is being created. Specified in the form <broker_monitor_host_name>:<port_number>. If you omit the port number, the default port number specified by BROKER_MONITOR_DEFAULT_PORT will be used.


BrokerCommFailureException A problem occurred while establishing the connection.

BrokerHostNotFoundException The specified Broker Monitor host cannot be located.

BrokerNotRunningException A Broker Monitor could not be found on the broker_monitor_host.

BrokerNullParameterException The broker_monitor_host parameter is null.

broker_monitor_host

The Broker Monitor host for which this Broker Monitor client is being created. Specified as <broker_monitor_host_name>:<port_number>. If you omit the port number, the default port number specified by BROKER_MONITOR_DEFAULT_PORT will be used.

desc The connection descriptor to use for the new BrokerMonitorClient. If null, a default connection will be established.



Methods

destroy

void destroy() throws BrokerException

Destroys the Broker Monitor client. Marks the local Broker Monitor client object as disconnected and throws an exception.

getHostName

String getHostName()

Returns the host name of the Broker Monitor.

getPort

int getPort()

Returns the port number used by the Broker Monitor.

getServerLogEntries

BrokerServerLogEntry[] getServerLogEntries( int base_port, BrokerDate first_entry, String locale, int num_entries) throws BrokerException


BrokerCommFailureException A problem occurred while establishing the connection.

BrokerHostNotFoundException The specified Broker Monitor host cannot be located.

BrokerNotRunningException A Broker Monitor could not be found on the broker_monitor_host.

BrokerNullParameterException The broker_monitor_host parameter is null.

Possible Exception Meaning

BrokerInvalidClientException The Broker Monitor client has been destroyed or disconnected.

base_port The port number of the Broker Server to which this Broker Monitor client is connected.



Returns a BrokerServerLogEntry array containing the desired log entries of the Broker Server to which this Broker Monitor client is connected. You specify the date of the first entry, the locale, and the number of entries. The parameter num_entries can be set to the number of entries desired or to SERVER_LOG_ALL_ENTRIES if you wish all entries to be returned.

Note: Attempting to obtain all server log entries may create performance problems and may use up significant memory.

getServerLogStatus

BrokerServerLogInfo getServerLogStatus( int base_port) throws BrokerException

Returns the log status for the Broker Server to which this Broker Monitor client is connected. The BrokerServerLogInfo object returned contains the date and time of the first and last log entries, as well as the current number of entries in the log.

first_entry The date of the first entry desired. If null, the entries will start with the first one that appears in the Broker Server's log.

locale The locale. If set to null, the Broker Server's default locale is used.

num_entries The maximum number of log entries desired. If set to SERVER_LOG_ALL_ENTRIES, all entries in the log will be retrieved.


BrokerIncompatibleVersionException Broker Server version does not support this operation.

BrokerInvalidClientException TheBroker Monitor client has been destroyed or disconnected.

BrokerNoPermissionException The Broker Monitor client has limited access.

BrokerOutOfRangeException The value of num_entries parameter is less than -1.

base_port The port number of the Broker Server.







getServerRunStatus

int getServerRunStatus( int port) throws BrokerException

Returns the current status of the Broker Server. Returns one of the following values of the Broker Server:

SERVER_STATUS_ERROR

SERVER_STATUS_RUNNING

SERVER_STATUS_STARTING

SERVER_STATUS_STOPPED

SERVER_STATUS_STOPPING

getServers

BrokerServerInfo[] getServers() throws BrokerException

Returns the configuration details of all Broker Servers on the specified host.

getVersion

String getVersion() throws BrokerException

Returns the version of Broker Monitor.

port The port number of the Broker Server.



BrokerUnknownServerException No Broker Server is configured on the specified port.


BrokerInvalidClientException TheBroker Monitor client has been destroyed or disconnected.





getVersionNumber

int getVersionNumber()

Returns the version number of Broker Monitor. Returns the version number of Broker Monitor client if Broker Monitor is newer than the Broker Monitor client's version.

pruneMonitorLog

void pruneMonitorLog( int base_port BrokerDate older_than) throws BrokerException

Deletes entries from the Broker Monitor log. Deletes all entries that are older than or equal to the date specified by the older_than parameter.

reloadConfig

void reloadConfig() throws BrokerException

Broker Monitor reloads the configuration of all the connected Broker Servers.

reloadConfigForServer

void reloadConfigForServer( int port ) throws BrokerException

Broker Monitor reloads the configuration of the Broker Server running on port.

base_port The port number of the Broker Server.

older_than The date for deleting entries that are older than or equal to the older_than date.





BrokerNullParameterException The value of the older_than parameter is null.




startServer

void startServer( int port ) throws BrokerException

Broker Monitor client starts the Broker Server configured on the specified port.

toString

String toString()

Returns the Broker Monitor client details. Returns null if the Broker Monitor client is not valid.

BrokerProcessInfo

class BrokerProcessInfo extends java.lang.Object

This class is used to contain process information for a Broker.

Variables

data_directory

String data_directory

The directory where data for the Broker will be written.

exectuable_name

String exectuable_name










The name of the Broker's executable file.

Constructors

BrokerProcessInfo

BrokerProcessInfo()

Creates an uninitialized process information object.

BrokerProcessInfo

BrokerProcessInfo( String new_name, String new_directory)

Creates an initialized process information object.

BrokerQueueBrowserinterface BrokerQueueBrowser

This interface provides queue browsing capabilities to view events from both client queues and forwarding queues.

Methods

browseEvents


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.


new_name The name of the Broker's executable file.

new_directory The name of the directory where the Broker's output will be written.




closeQueueBrowser

void closeQueueBrowser() throws BrokerException

Closes the current client queue or forwarding queue browser object; otherwise throws Broker exception.

getBrowserInfo

BrokerQueueBrowserInfo getBrowserInfo() throws BrokerException

Gets information about the current client queue browser. Returns a BrokerQueueBrowserInfo object.

getFilters

COM.activesw.api.client.BrokerFilterDescriptor[] getFilters() throws BrokerException

Returns the list of filters currently set on the client queue browser.


BrokerTimeoutException The timeout is reached before an event arrives.



BrokerQueueBrowserException The event at the last cursor position was removed. Reset the cursor to a valid position before attempting a browse operation.

BrokerQueueBrowserException The queue is busy; retry the operation later.

BrokerQueueBrowserException The queue is empty and no more events can be returned. For forwarding queues, this exception might be thrown when there are only internal events within the requested browsing range.

BrokerInvalidClientException The client has been destroyed or is disconnected.







resetFilters


Removes the filters set on the client queue browser. Any subsequent browse requests would consider all the events in the queue.

setFilter

void setFilter( COM.activesw.api.client.BrokerFilterDescriptor filter) throws BrokerException

Sets the filter for the client queue browser's browse operation. Any subsequent browse requests would return only those events that satisfy the filter condition. If a filter for the specified document type already exists on the queue browser, it will be overwritten with the new filter setting.

setFilters

void setFilters( COM.activesw.api.client.BrokerFilterDescriptor[] filters) throws BrokerException

Sets multiple filters for the client queue browser's browse operation. Any subsequent browse requests would return only those events that satisfy the filter conditions. If a filter for the specified document type already exists on the queue browser, it will be overwritten with the new filter settings.








BrokerUnknownEventTypeException The specified event type on the filter object does not exist on Broker.





setPosition


Set the browser's cursor position to the specified position on the client queue or forwarding queue, where a value of '0' represents the head of the queue and a value of "queue length minus one" represents the end of the queue. Valid position values are in the range of 0 and "queue length-1".

BrokerQueueBrowserInfo

class BrokerQueueBrowserInfo extends java.lang.Object

This class holds detailed information of a queue browser.

Variables

clientId

String clientId

The ID of the client queue or forwarding queue being browsed.

browserId

String browserId




BrokerUnknownEventTypeException The specified event type on the filter object does not exist on Broker.


BrokerQueueBrowserException The queue browser is invalid or the specified queue position is out of bounds: the position is less than zero or the position is greater than/equal to the queue length.




Client ID of the client that is browsing the queue.

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

Create an empty lock info object.


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.



Variables

SERVER_STATUS_ERROR





SSL_STATUS_DISABLED

SSL_STATUS_ENABLED

SSL_STATUS_ERROR

SSL_STATUS_NOT_SUPPORTED

Constructors

BrokerServerClient

BrokerServerClient( String broker_host, BrokerConnectionDescriptor desc) throws BrokerException

Creates a BrokerServerClient object for the specified Broker Server.

A Broker Server client is said to have limited access if it is not authorized under the host's Access Control List. Some methods offered by this class will throw a BrokerNoPermissionException if the client has limited access.

Note: The shared state flag of the BrokerConnectionDescriptor associated with this client is always ignored.

broker_host The Broker host for which this administrative client is being created. Specified in the form <broker_host_name>:<port_number>. If you omit the port number, the default port number will be used. For example: MyHost:12000

desc The connection descriptor to use for the new BrokerServerClient. If null, a default connection will be established.






Methods

createBroker

void createBroker( String broker_name, String description, boolean is_default) throws BrokerException

Creates a Broker with the specified broker_name on the host to which this BrokerServerClient is currently connected.

Note: For information on Broker name restrictions, see the webMethods Broker Client Java API Programmer’s Guide.

destroy

void destroy() throws BrokerException

Destroys this BrokerServerClient object, disconnecting from the Broker Server in the process. This BrokerServerClient object is marked as disconnected even if an exception is thrown.


BrokerNullParameterException The broker_host parameter is null.

broker_name The name of the Broker that is being created.

description A description of this Broker.

is_default If set to true, this will be the default Broker for this host.


BrokerExistsException A Broker with the same broker_name already exists on the host.

BrokerInvalidBrokerNameException The broker_name is not valid.


BrokerNoPermissionException Permission to create a Broker on the host was denied.

BrokerNullParameterException broker_name or description parameter is null.




See Also:

BrokerServerClient.getActivePort

getActivePort

int getActivePort() throws BrokerException

Returns the base port number currently in use by the Broker host. The base port is used for non-SSL connections and has a default value of 6849. The base port number is also used to calculate the port numbers shown in the table in BrokerAdminTypeDef on page 302.

The following table shows the port numbers calculated from the base port number.

getActiveProcessInfo

BrokerProcessInfo getActiveProcessInfo() throws BrokerException

Returns the process information currently for the Broker Server.

See BrokerProcessInfo on page 401 for information on the returned object.

getActiveSSLConfig

BrokerSSLConfig getActiveSSLConfig() throws BrokerException



Port number Description

base port minus 1 Used for SSL connections without client authentication.

base port minus 2 Used for SSL connections with client authentication.





BrokerNoPermissionException Client does not have permission to obtain the Broker's active port.



Returns a BrokerSSLConfig object that represents the Broker Server's current SSL configuration. This may or may not be the same as the saved SSL configuration, which will take effect the next time the Broker Server is started.

Important! This method only works with Broker Server 6.5.2 version or earlier.

See Also:

BrokerServerClient.getSavedSSLConfig, BrokerServerClient.getSSLStatus, and BrokerServerClient.setSSLConfig

getActiveSSLConfigV2

BrokerSSLConfigV2 getActiveSSLConfigV2() throws BrokerException

Returns a BrokerSSLConfigV2 object that represents the Broker Server's current SSL configuration. This may or may not be the same as the saved SSL configuration, which will take effect the next time the Broker Server is started.

See Also:

BrokerServerClient.getSavedSSLConfig, BrokerServerClient.getSSLStatus, and BrokerServerClient.setSSLConfig

getActiveSSLIdentity

BrokerSSLIdentity getActiveSSLIdentity() throws BrokerException

Returns a BrokerSSLIdentity object that provides information about the Broker Server's SSL identity (DNs).



BrokerNoPermissionException The client does not have permission to obtain the Broker's active SSL configuration.



BrokerNoPermissionException The Client does not have permission to obtain the Broker's active SSL configuration.

BrokerIncompatibleVersionException If the Broker does not support the old form of SSL configuration.



Important! This method only works with Broker Servers 7.1 version and higher.

getBasicAuthIdentity

public BrokerBasicAuthIdentity getBasicAuthIdentity() throws BrokerException

Returns the Broker Server's basic authentication identity that is in use.

Note: This method only works with Broker Servers version 8.2 and higher.

See Also:

BrokerServerClient.setBasicAuthIdentity

getBasicAuthStatus

public boolean getBasicAuthStatus() throws BrokerException

Returns whether basic authentication is configured on Broker Server. The possible values are "True" and "False". This operation is open to all users.



BrokerNoPermissionException Client does not have permission to obtain the Broker's active SSL configuration.


BrokerInvalidClientException The BrokerServerClient has been destroyed or is disconnected.

BrokerNoPermissionException The client does not have permission to obtain the Broker's basic authentication identity.








getSavedSSLidentity

BrokerSSLIdentity getSavedSSLIdentity() throws BrokerException

Returns a BrokerSSLIdentity object that provides information about the Broker Server's SSL identity (DNs).


getAdminACL

BrokerAccessControlList getAdminACL() throws BrokerException

Returns a BrokerAccessControlList object containing the distinguished names of the entities that may perform administration operations on the Broker Server.

See Also:

BrokerServerClient.setAdminACL

getBrokers

BrokerInfo[] getBrokers() throws BrokerException

Returns an array of BrokerInfo objects representing all the Brokers available on the host to which this BrokerServerClient is connected. All administrative clients have permission to use this method.



BrokerNoPermissionException The client does not have permission to obtain the Broker's active SSL configuration.



BrokerNoPermissionException Client does not have permission to obtain the host's Access Control List.



See Also:

BrokerServerClient.getDefaultBrokerName

getDefaultBrokerName

String getDefaultBrokerName() throws BrokerException

Returns a string containing the name of the default Broker on the host to which this BrokerServerClient is connected. All administrative clients have permission to use this method.

A null string is returned if there is no default Broker.

See Also:

BrokerServerClient.getBrokers and BrokerServerClient.setDefaultBrokerName

getDescription

String getDescription() throws BrokerException

Returns a string containing a description for the Broker Server.

See Also:

BrokerServerClient.setDescription

getDNsFromCertFile

String[] getDNsFromCertFile( String certificate_file, String password) throws BrokerException







certificate_file The certificate file whose distinguished names are to be returned. If null, the host's active certificate file is used.



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.


See Also:

BrokerServerClient.getActiveSSLConfig, BrokerServerClient.getSavedSSLConfig, and BrokerServerClient.setSSLConfig

getFIPSMode

String getFIPSMode() throws BrokerException

Returns the version of the OpenSSL used if the FIPS mode is enabled in Broker Server. Returns null if the FIPS mode is disabled.

password The password for accessing the certificate_file. May be null if the certificate_file parameter is null or if the host's active certificate file uses the same password.


BrokerFileNotFoundException The specified certificate_file could not be found.


BrokerNoPermissionException The password is invalid, or certificate_file does not contain certificates, or the client does not have permission to access the SSL information.



BrokerIncompatibleVersionException The Broker does not support FIPS.

BrokerNoPermissionException The client does not have permission to access the FIPS information.

BrokerTimeoutException The FIPS information was not returned within the time-out interval.



getHostName


String getHostName()

Returns the host name associated with this Broker host.

getLicense

String getLicense() throws BrokerException

Returns a string containing the full path to the Broker host's license file.

Note: Returns a string containing the Broker host's license for Broker Servers earlier than 8.2 version.

See Also:

BrokerServerClient.setLicense

getLicenseContent

String getLicenseContent() throws BrokerException

Returns a string containing the Broker host's license file content.

See Also:

BrokerServerClient.setLicenseContent



BrokerNoPermissionException The client does not have permission to access the SSL information.






getLogConfig

BrokerLogConfig getLogConfig() throws BrokerException

Returns a BrokerLogConfig object that represents the Broker Server's logging configuration. This operation is available to all users.

See Also:

BrokerServerClient.setLogConfig

getPublicationProcessingState

int getPublicationProcessingState() throws BrokerException {

Returns the publication processing state of the Broker Server. A return value of 0 indicates that event publication is active. A return value of 1 indicates that event publication is paused.

See Also:

BrokerServerClient.pruneServerLog and BrokerServerClient.resumePublishProcessing.

getRootDNsFromCertFile

String[] getRootDNsFromCertFile( String certificate_file, String password) throws BrokerException

Returns the list of trusted root distinguished names available in the certificate_file on the Broker Server.

If the password and certificate_file parameters are both null, the Broker's active certificate file and password are used.





certificate_file The certificate file whose trusted root distinguished names are to be returned.

password The password for the certificate file. May be null if certificate_file is also null.



If the Broker does not currently have an active SSL configuration, then null parameter exceptions will be returned as appropriate.


getDNFromKeyStore

String getDNsFromKeystore( String keystore, String password, BrokerSSLConfigV2.KeystoreType keystoreType) throws BrokerException

Returns the distinguished name from the certificate in the specified keystore.

See BrokerSSLConfigV2 on page 447 for more information.


See Also:

BrokerServerClient.getSSLStatus.


BrokerFileNotFoundException The specified certificate_file could not be found or could not be read.


BrokerNoPermissionException The password specified is not valid or certificate_file does not contain certificates.

keystore The certificate file whose distinguished name is to be returned.

password The password for the keystore file. May be null if keystore is also null.

keystoreType The keystoreType parameter specifies the type of keystore: either PKCS12 or PEM.






getIssuerDNFromKeystore

String[] getIssuerDNFromKeystore( String keystore, String password, BrokerSSLConfigV2.KeystoreType keystoreType) throws BrokerException

Returns the issuer distinguished name in the given keystore on the Broker Server.

getRootDNsFromTrustStore

String getDNsFromKeystore( String truststore, throws BrokerException

Returns the distinguished name from the trusted root certificate in the specified trust store.

See BrokerSSLConfigV2 on page 447 for more information.


See Also:

BrokerServerClient.getSSLStatus.

getSavedSSLConfig

BrokerSSLConfig getSavedSSLConfig() throws BrokerException


BrokerFileNotFoundException If the keystore is not found or cannot be read.

BrokerInvalidClientException The client has been destroyed.

BrokerNoPermissionException If the password is invalid or if the file is not a keystore, or if the client has limited access.

BrokerNullParameterException If keystore is null.

BrokerSSLConfigException If the keystoreType is invalid.

truststore The trusted root whose distinguished name is to be returned.






Returns the SSL configuration the Broker host will use the next time it is started. This may differ from the current SSL configuration.

See BrokerSSLConfig on page 446 for more information.


See Also:

BrokerServerClient.getActiveSSLConfig, BrokerServerClient.getSSLStatus, and BrokerServerClient.setSSLConfig.

getSavedSSLConfigV2

BrokerSSLConfigV2 getSavedSSLConfigV2() throws BrokerException

Returns the SSL configuration the Broker host will use the next time it is started. This may differ from the current SSL configuration.

See BrokerSSLConfig on page 446 for more information.

See Also:

BrokerServerClient.getActiveSSLConfig, BrokerServerClient.getSSLStatus, and BrokerServerClient.setSSLConfig.

getSavedSSLIdentity

BrokerSSLIdentity getSavedSSLIdentity() throws BrokerException

Returns the Broker Server's SSL identity that will be used the next time the Broker Server is restarted. This may not be the same as the active identity.







BrokerIncompatibleVersionException If the Broker does not support the old form of SSL configuration.




getServerLogEntries

BrokerServerLogEntry[] getServerLogEntries( BrokerDate first_entry, String locale, int num_entries) throws BrokerException

Returns a BrokerServerLogEntry array containing the desired Broker Server log entries. You specify the date of the first entry, the locale you provide, and the number of entries you desire. The parameter num_entries can be set to the number of entries desired or to SERVER_LOG_ALL_ENTRIES if you wish all entries to be returned.

Note: Attempting to obtain all server log entries may create performance problems and may use up significant amounts of memory.

For more information on the log entry format, see BrokerServerLogEntry on page 439.




BrokerIncompatibleVersionException If the Broker does not support this call.

first_entry The date of the first entry desired. If null, the entries will start with the first one that appears in the Server's log.

locale The locale. If set to null, the server's default locale is used.

num_entries The maximum number of log entries desired. If set to SERVER_LOG_ALL_ENTRIES, all entries in the log will be retrieved.





BrokerOutOfRangeException The n parameter is less than -1.



See Also:

BrokerServerClient.getServerLogStatus and BrokerServerClient.pruneServerLog

getServerLogStatus

BrokerServerLogInfo getServerLogStatus() throws BrokerException

Returns the log status for the Broker Server to which this client is connected. The BrokerServerLogInfo object that is returned contains the date and time of the first and last log entries as well as the current number of entries in the log.

See Also:

BrokerServerClient.getServerLogEntries and BrokerServerClient.pruneServerLog

getServerProcessRunStatus

static int getServerProcessRunStatus( String broker_host) throws BrokerException

Returns the state of the Broker Server process on the specified broker_host. Returns one of the following values:

SERVER_STATUS_ERROR









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



See Also:

BrokerServerClient.startServerProcess and BrokerServerClient.stopProcess

getServerProcessRunStatus

static int getServerProcessRunStatus( String broker_monitor_host, int monitor_port, int broker_port) throws BrokerException

Returns the state of the Broker Monitor process on the specified broker_host. Returns one of the following values:

SERVER_STATUS_ERROR










BrokerUnknownServerException The specified broker_host has a monitor process running, but no server is specified on the port number specified.

broker_monitor_host The name of the Broker Monitor host that manages the Broker Server whose state is to be returned.

monitor_port The port number of the Broker Monitor. If you omit the port number, the default port number will be used (6850).

broker_port The name of the Broker Server whose state is to be returned. The default is localhost:6849. Use this option to specify other Broker Servers on the local machine.





See Also:

BrokerServerClient.startServerProcess and BrokerServerClient.stopProcess

getServerVersionNumber

int getServerVersionNumber()

Returns the version number of the Broker Server that is executing the Broker to which this admin_client is connected. If the Broker Server's version number is newer than the client's version, the client's version number is returned.

See Also

BrokerServerClient.getVersion

getSSLStatus

BrokerSSLStatus getSSLStatus() throws BrokerException

Returns a BrokerSSLStatus object representing the current SSL status for the Broker host.

See Also:

BrokerServerClient.getSavedSSLConfig, BrokerServerClient.getActiveSSLConfig, and BrokerServerClient.setSSLConfig.

getStats

BrokerEvent getStats() throws BrokerException




BrokerUnknownServerException The specified broker_host has a monitor process running, but no server is specified on the port number specified.






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:


createTime BrokerDate The time the server was first started.

highestNumConnections int The highest number of non-SSL connections since the server was started.

highestNumSSLConnections int The highest number of SSL connections since the server was started.

highestNumConnectionsTime BrokerDate The time when highestNumConnections was last changed.

highestNumSSLConnectionsTime BrokerDate The time when highestNumSSLConnections was last changed.

isDiskSpaceLow boolean Set to true if there is less than 1 megabyte of free disk space.

isDiskSpaceVeryLow boolean Set to true if there is less than 100 kilobytes of free disk space.

isLicenseExpiringSoon boolean Set to true if the server's license will expire within a week.

isLicenseExpired boolean Set to true if the server's license has expired.

licensedConnections int Total number of connections, SSL and non-SSL, allowed by the server's license. If -1, there is no limit.

licenseExpirationTime BrokerDate Date when the server's license will expire. If zero, it will never expire.

licensedSSLConnections int Total number of SSL connections allowed by the server's license. If -1, there is no limit.

licenseTimeRemaining int The number of seconds until the server's license expires. If zero, it will never expire.


numConnections int The number of non-SSL connections to this server.

numSSLConnections int The number of SSL connections to this server.



See Also:

BrokerServerClient.getUsageStats

getUsageStats

BrokerEvent getUsageStats() throws BrokerException

Returns a BrokerEvent containing system resource usage statistics for the Broker Server. Each statistic is stored as a field in the event as shown in the following table:

serverStartTime BrokerDate The time the server was most recently started.




guaranteedDiskFree long The number of kilobytes of free space available to the operating system on the disk partition. This should not be confused with the amount of free space currently available to the Broker system, described by guaranteedSpaceReserved.

guaranteedDiskName string The name of the guaranteed disk partition. On a Windows platform, this is usually C:.

guaranteedDiskSize long The total number of kilobytes of disk space available to the operating system on the disk partition. This should not be confused with the amount of disk space allocated to the Broker system, described by guaranteedSpaceMax.

guaranteedSpaceAllocated long The number of kilobytes of disk space currently allocated for guaranteed space.

guaranteedSpaceMax long The maximum number of kilobytes, due to operating system limits, that the Broker system can use for guaranteed storage. Disk space reservation limits may be exceeded before this limit is reached.




guaranteedSpaceReserved long The maximum guaranteed space available to Broker minus the space actually used by Broker (guaranteedSpaceMax minus guaranteedSpaceUsed). If this value is zero, the amount of guaranteed storage for the Broker system may need to be increased.

guaranteedSpaceUsed long The maximum number of kilobytes of disk space that has ever been used by the Broker system at any point in time for guaranteed space. This number acts as a "high watermark."

maxMemorySize long The number of kilobytes of space Broker sets as a limit for memory usage.

memoryUsed long The total number of kilobytes of space allocated by Broker on the heap.


percentageCPUUsed double Percentage of CPU used by the Broker Server. This is a cumulative value since the creation of the current Broker Server process. This value is not set for Windows platforms.

persistentDiskFree long The number of free kilobytes of persistent disk store space.

persistentDiskName string The name of the persistent disk partition.

persistentDiskSize long The maximum number of kilobytes, due to system limits, that persistent storage can consume. Disk space reservation limits may be exceeded before this limit is reached.

persistentSpaceAllocated long The number of kilobytes of disk space currently allocated for persistent space.

persistentSpaceMax long The fixed number of kilobytes of disk space reserved for persistent space. If zero, the storage will be resized as needed.

persistentSpaceUsed long The number of kilobytes of disk space being used for persistent space.




See Also:

BrokerServerClient.getStats.

getVersion

String getVersion()

Returns a string containing the Broker Server version string. Since the version string is complex, it is recommended that you use the BrokerServerClient.getServerVersionNumber method if you want to retrieve just the version number.

See:

BrokerServerClient.getServerVersionNumber.

pruneServerLog

void pruneServerLog( BrokerDate older_than) throws BrokerException

Deletes all log entries from the Broker Server to which this client is connected. All entries with a date equal to, or older than, the date specified by older_than will be deleted.

swapSpaceFree long The number of kilobytes of free swap space.

swapSpaceMax long The total number of kilobytes of swap space.

systemTimeUsed double The number of seconds of CPU system time used by the Broker Server since it was started.

userTimeUsed double The number of seconds of CPU user time used by the Broker since it was started.



older_than The date of the entries that are to be deleted from the log.






See Also:

BrokerServerClient.getServerLogEntries and BrokerServerClient.getServerLogStatus

registerConnectionCallback

void registerConnectionCallback( BrokerServerConnectionCallback obj, Object client_data) throws BrokerException

Registers a connection callback object obj for this Broker Server client. The callback object's handleHostConnectionChange method will be invoked if this client is disconnected or reconnected. If a callback object was already registered for this client, it will be replaced by the new callback object.

You may un-register a previously registered callback object by invoking this method with a null obj parameter. For more information, see BrokerServerConnectionCallback on page 438.

See Also:

BrokerServerConnectionCallback.handleHostConnectionChange

resumePublishProcessing

void resumePublishProcessing() throws BrokerException {

This methods resumes event publishing on the Broker Server.



BrokerNullParameterException The older_than parameter is null.

obj The object whose BrokerServerConnectionCallback.handleHostConnectionChange method will be invoked when this BrokerServerClient is disconnected or reconnected.

client_data Data that is to be passed to the BrokerServerConnectionCallback.handleHostConnectionChange callback method. This may be set to null.






To check the state of publication processing for the Broker Server, check the return value for getPublicationProcessingState.

See Also:

BrokerServerClient.getPublicationProcessingState and BrokerServerClient.pruneServerLog.

setAdminACL

void setAdminACL( BrokerAccessControlList acl) throws BrokerException

Sets the Broker Server's access control list. This list is used to determine the entities that may create a BrokerServerClient to administer this Broker Server.

See AccessControlList on page 175 for more information.

See Also:

BrokerServerClient.getAdminACL

setBasicAuthIdentity

public void setBasicAuthIdentity( BrokerBasicAuthIdentity new_identity) throws BrokerException

Sets the Broker Server's identity for basic authentication. To disable the basic authentication identity, set the basic authentication username to null.



acl The access control list to set for this Broker Server.




BrokerNoPermissionException The client does not have permission to set the host's Access Control List.


new_identity The authentication identity that is to be set on Broker Server.




See Also:

BrokerServerClient.getBasicAuthIdentity

setDefaultBrokerName

void setDefaultBrokerName( String broker_name) throws BrokerException

Sets the name of the default Broker for the host. The default Broker is the one to which Broker clients will be connected if they do not specify a Broker name when creating or reconnecting a Broker client.

setDescription

void setDescription( String description) throws BrokerException

Sets the description for this Broker Server.


BrokerBasicAuthFailureException Basic authentication failed for the user.

BrokerNullParameterException The new_identity parameter is null.

BrokerIncompatibleVersionException Broker Server does not support this operation.

broker_name The name of the Broker that is to be the default Broker. If null, there will be no default Broker for this host.



BrokerNoPermissionException The client does not have permission to set the default Broker.

BrokerUnknownBrokerNameException The specified broker_name does not exist.

description The description to set for this Broker Server.





See Also:

BrokerServerClient.getDescription

setLicense

void setLicense( String license) throws BrokerException

Sets the license for the host to which this BrokerServerClient is currently connected.

See Also:

BrokerServerClient.getLicense

setLicenseContent

void setLicenseContent( String licenseFileContent) throws BrokerException

Sets the license file content for the host to which this BrokerServerClient is currently connected. This is supported by webMethods Broker 8.0 and above.

BrokerNoPermissionException The client does not have permission to set the description.


license The full path of the license file to be used.

Note: Type the license string for Broker Servers earlier than 8.2 version.



BrokerInvalidLicenseException The license is invalid.

BrokerNoPermissionException The client does not have permission to set the license.

BrokerNullParameterException The license parameter is null.

licenseFileContent The unabridged contents of the license file to be used by webMethods Broker.




See Also:

BrokerServerClient.getLicenseContent

setLicenseFile

void setLicenseContent( String licenseFile) throws BrokerException

Sets the license file for the host to which this BrokerServerClient is currently connected. This is supported by webMethods Broker 8.0 and above.

See Also:

BrokerServerClient.getLogConfig

setLogConfig

void setLogConfig( BrokerLogConfig log_config) throws BrokerException

Sets the Broker Server's logging configuration.





BrokerNullParameterException The licenseFileContent parameter is null.

licenseFile The full path of the license file to be used by webMethods Broker.





BrokerNullParameterException The licenseFile parameter is null.

log_config The new logging configuration to set.



See BrokerLogConfig on page 387 for more information.

See Also:

BrokerServerClient.getLogConfig

setSSLConfig

void setSSLConfig( BrokerSSLConfig new_config) throws BrokerException

Sets the SSL configuration to be used by the Broker Server. The first time the SSL configuration is set for a Broker Server, it will take effect immediately. Subsequent configurations will take effect the next time the Broker Server is started. This means that the configuration set by this method may be different from the currently active SSL configuration.

To disable SSL for this Broker Server, set the certificate file contained in new_config to null.

To change a distinguished name within the same file, set the password to null and the certificate file to the same file.

For more information, see BrokerSSLConfig on page 446.




BrokerInvalidLogConfigException One or more log configuration entries are invalid. If throw, all valid entries are still set.

BrokerNoPermissionException The client does not have permission to access the log configuration.

new_config The SSL configuration to use the next time the Broker Server is started.


BrokerFileNotFoundException The certificate file specified by new_config cannot be found.




See Also:

BrokerServerClient.getActiveSSLConfig, BrokerServerClient.getDNsFromCertFile, BrokerServerClient.getSavedSSLConfig, and BrokerServerClient.getSSLStatus

setSSLConfig

void setSSLConfig( String certificate_file, String password, String distinguished_name) throws BrokerException

Sets the SSL configuration to be used by the Broker Server. The first time the SSL configuration is set for a Broker Server, it will take effect immediately. Subsequent configurations will take effect the next time the Broker Server is started. This means that the configuration set by this method may be different from the currently active SSL configuration.

To disable SSL for this Broker Server, set the certificate_file to null.

To change the distinguished name without changing the certificate file, you can set the password to null.


BrokerNoPermissionException The parameter new_config specifies an invalid password or an invalid certificate file, or the client does not have permission to set this configuration.

BrokerNullParameterException The parameter new_config specifies a certificate file, but the distinguished name is null. Or new_config is null.

BrokerUnknownNameException The distinguished name specified by new_config does not exist in the certificate file.

certificate_file The certificate file whose distinguished names are to be used. If null, SSL will be disabled the next time this Broker Server is started.

password The password for accessing the certificate_file. May be null if the certificate_file parameter is null or if certificate file name is not to be changed.

distinguished_name The distinguished name to be used by the Broker when it authenticates itself to Broker clients.




See Also:

BrokerServerClient.getActiveSSLConfig, BrokerServerClient.getDNsFromCertFile, BrokerServerClient.getSavedSSLConfig, and BrokerServerClient.getSSLStatus

setSSLConfig

void setSSLConfig( BrokerSSLConfigV2 config) throws BrokerException

Sets the SSL configuration to be used by the Broker Server. The first time the SSL configuration is set for a Broker Server, it will take effect immediately. Subsequent configurations will take effect the next time the Broker Server is started. This means that the configuration set by this method may be different than the currently active SSL configuration.

For more information, see BrokerSSLConfigV2 on page 447.



BrokerFileNotFoundException The specified certificate_file could not be found.


BrokerNoPermissionException The password is invalid, or certificate_file does not contain certificates, or the client does not have permission to modify the SSL information.

BrokerNullParameterException The distinguished_name parameter is null, but the certificate_file is not null.

config The SSL configuration to use the next time the Broker Server is started.


BrokerFileNotFoundException The keystore file specified by config cannot be found.


BrokerNoPermissionException The parameter config specifies an invalid password or an invalid certificate file, or the client does not have permission to set this configuration.

BrokerNullParameterException The parameter config specifies a keystore file, but the distinguished name is null. Or config is null.



startServerProcess

void startServerProcess( String broker_host) throws BrokerException

Starts the Broker Server process on the specified host if it is not already started.

See Also:

BrokerServerClient.getServerProcessRunStatus and BrokerServerClient.stopProcess

startServerProcess

void startServerProcess( String broker_monitor_host int monitor_port int broker_port) throws BrokerException

BrokerUnknownNameException The distinguished name specified by config does not exist in the keystore file.

broker_host The name of the host where the Broker host process is to be started. Specified in the form <broker_host_name>:<port_number>. If you omit the port number, the default port number will be used.




BrokerNoPermissionException The client does not have permission to start Broker host process.



BrokerSecurityException The client is now in limited access mode because its distinguished name was not found in the Broker host's Access Control List.

broker_monitor_host The name of the Broker Monitor host that monitors the Broker Server whose process is to be started. Specified in the form <broker_host_name>:<port_number>. If you omit the port number, the default port number will be used.




Starts the Broker Server process on the specified host if it is not already started.

See Also:

BrokerServerClient.getServerProcessRunStatus and BrokerServerClient.stopProcess

stopProcess

void stopProcess() throws BrokerException

Stops the Broker Server process, if it has not already been stopped, and destroys this Broker Server client.

See Also:

BrokerServerClient.getServerProcessRunStatus and BrokerServerClient.startServerProcess

monitor_port The port number of the Broker Monitor. If you omit the port number, the default port number will be used (6850).

broker_port The port number of the Broker Server whose state is to be returned. The default is localhost:6849. Use this option to specify other Broker Servers on the local machine.




BrokerNoPermissionException The client does not have permission to start Broker host process.



BrokerSecurityException The client is now in limited access mode because its distinguished name was not found in the Broker host's Access Control List.



BrokerNoPermissionException The client does not have permission to stop the Broker host process.



toString

String toString()

Returns a string containing the BrokerServerClient information in a human-readable format.

BrokerServerConnectionCallback

interface BrokerConnectionCallback

You use this interface to implement an object for handling connection notification for a Broker Server client. You provide an implementation for the handleHostConnectionChange method, which will be invoked when the Broker Server client is disconnected or reconnected from its Broker Server.

You register a BrokerServerConnectionCallback-derived object using the BrokerServerClient.registerConnectionCallback method.

Methods

handleHostConnectionChange

void handleHostConnectionChange( BrokerServerClient client, int connect_state, Object client_data);

You provide an implementation of this callback method to handle host client connection notification. You can implement this method to recreate any needed client state that may have been lost or to provide other functions, such as logging of error messages.

When the BrokerConnectionCallback object's callback method is invoked, that method's connect_state parameter will be set to one of the BrokerClient variables as shown in the following table:

client The Broker Server client whose connection state has changed.

connect_state The client's connection state. This will be set to one of the values shown in the table below.

client_data Any data that your callback method needs to perform its processing. This data is defined when you register your BrokerServerConnectionCallback object.


CONNECT_STATE_DISCONNECTED The BrokerServerClient has been disconnected.

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



See Also:

BrokerServerClient.registerConnectionCallback

BrokerServerLogEntry

class BrokerServerLogEntry

This class is used to represent an entry in a Broker Server's log.

Constants

SERVER_LOG_MESSAGE_ALERT

SERVER_LOG_MESSAGE_INFO

SERVER_LOG_MESSAGE_UNKNOWN

SERVER_LOG_MESSAGE_WARNING

Variables

entry_msg_id

short entry_msg_id

The log entry's identifier.

entry_msg_text

String entry_msg_text

The log entry's text.

entry_type

short entry_type

The log entry's type, which should be one of the SERVER_LOG_* values described above.

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




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.



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



This class stores information about how an event type is shared across a territory gateway.

Variables

accept_publish

boolean accept_publish

Set to true if the this territory accepts having events being published or delivered from the remote territory.

accept_subscribe

boolean accept_subscribe

Set to true if this territory can forward subscriptions or deliver events to the remote territory.

event_type_name

String event_type_name

The name of the event type.

is_synchronized

boolean is_synchronized

If set to true, the event type is synchronized with the remote territory. If false, the value of accept_publish and accept_subscribe are ignored since the event type will not flow between territories.

subscribe_filter

String subscribe_filter

Specifies a filter that controls which events of this type will be forwarded to other territories. If set to null, no filtering of events of this type will occur. For more information on subscription filters, see the webMethods Broker Client Java API Programmer’s Guide.

Constructors


BrokerSharedEventTypeInfo()

Creates an empty BrokerShareEventTypeInfo object.




BrokerSharedEventTypeInfo( String event_type, boolean accept_pub, boolean accept_sub)

Creates and initializes a BrokerShareEventTypeInfo object.

Methods

toString

String toString()

Returns a string containing the Broker shared event type information in a human-readable format.

BrokerSharedEventTypeRefuseUpdateInfo

class BrokerSharedEventTypeRefuseUpdateInfo extends java.lang.Object

This class stores configuration information about how an event type is shared across a territory gateway. The class is used by BrokerAdminClient.setTerritoryGatewayRefuseEventTypeUpdates to obtain the event type for which the territory gateway will refuse updates.

Constructor

BrokerSharedEventTypeRefuseUpdateInfo

BrokerSharedEventTypeRefuseUpdateInfo( String event_type_name, boolean refuse_events, boolean refuse_updates) throws BrokerException

event_type The name of the event type to be shared.

accept_pub If set to true, this territory accepts event that are publish or delivered from a remote territory.

accept_sub If set to true, this territory can forward subscriptions or deliver events to the remote territory.




See Also:

BrokerAdminClient.setTerritoryGatewayRefuseEventTypeUpdates, BrokerAdminClient.getTerritoryGatewayRefuseEventTypeUpdates, BrokerAdminClient.setTerritoryGatewayRefuseAllUpdates, and BrokerAdminClient.getTerritoryGatewayRefuseAllUpdates

BrokerSSLCertificate

class BrokerSSLCertificate extends java.lang.Object

This class describes a Broker's SSL certificate, including the dates during which it is valid, the distinguished name, the distinguished name that issued it's certificate, and the serial number.

Variables

begin_date

BrokerDate begin_date

The date when the certificate first became valid.

distinguished_name

String distinguished_name

The distinguished name associated with this certificate.

end_date

BrokerDate end_date

refuse_events Whether or not this territory currently refuses events of the specified event type. If set to true, the territory will refuse events of the specified type; if set to false, the territory will not refuse those events.

refuse_updates Whether or not this territory refuses updates to the specified event type. If set to true, the territory will refuse updates to the specified event type; if set to false, the territory will not refuse the updates.


BrokerNullParameterException The event_type_name, refuse_events, or refuse_updates parameter is null.



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

Creates an empty certificate object.


BrokerSSLCertificate( String new_distinguished_name, String new_issuer_distinguished_name, String new_status, String new_serial_number BrokerDate new_begin_date BrokerDate new_end_date)

Creates a certificate object with the specified attributes.

new_distinguished_name The distinguished name for the certificate.

new_issuer_distinguished_name

The distinguished name of the authority that issued the certificate.

new_status The certificate's status.

new_serial_number The certificate's serial number.

new_begin_date The date when the certificate becomes valid.

new_end_date The date when the certificate expires.



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.



BrokerSSLConfig

BrokerSSLConfig( String cert_file, String password, String dist_name, String issuer_dist_name)

Creates an SSL configuration object with the specified certificate file, certificate file password, distinguished name, and issuer distinguished name.

BrokerSSLConfigV2

class BrokerSSLConfigV2 extends java.lang.Object

This class describes a Broker's SSL configuration, including its CRL, keystore file, truststore file, SSL protocols that can be used, cipher suites, and maximum number of certificates in a certificate chain.

Variables

CRLType

enum CRLType { PEM, DER }

KeystoreType

enum KeystoreType { PEM, PKCS12 }

TruststoreType

enum TruststoreType { PEM, DIR }

SSLProtocol

enum SSLProtocol { TLSv1, SSLv3, ALL }

cert_file The name of the certificate file to use.

password The certificate file's password.

dist_name The distinguished name the Broker Server will use when authenticating itself with Broker clients.

issuer_dist_name The distinguished name of the certificate authority that issued the Broker Server's certificate.



Constructors

BrokerSSLConfigV2

BrokerSSLConfigV2()

Creates an empty SSL configuration object.

BrokerSSLConfigV2

BrokerSSLConfigV2(BrokerSSLConfigV2)

Creates a copy of the specified SSL configuration.

Methods

getCipherSuites

String getCipherSuites()

Returns a string in OpenSSL cipher format that specifies the current encryption cipher suites.

setCipherSuites

void setCipherSuites(String newCipher_Suites)

Passes a string in OpenSSL cipher format that sets the allowable encryption cipher suites.

getCRL

String getCRL()

Returns a string containing the path to the SSL CRL file used by the SSL configuration.

setCRL

void setCRL(String crl)

Sets the full path to the SSL CRL file used by the SSL configuration on Broker Server.

getCRLType

BrokerSSLConfigV2.CRLType getCRLType()

Returns a BrokerSSLConfigV2. CRLType object containing the type of the SSL CRL file used by the SSL configuration.

crl The full path to the SSL CRL file used by the SSL configuration on Broker Server.



setCRLType

void setCRLType( String crlType) throws BrokerSSLConfigException

Sets the type of the SSL CRL file to be used by the SSL configuration. Throws BrokerSSLConfigException if the value of crlType is not valid.

getKeystore

String getKeystore()

Returns a string containing the file name of the keystore.

setKeystore

void setKeystore(String newKeystore)

Sets the SSL keystore to be used by the SSL configuration.

getKeystorePassword

String getKeystorePassword()

Returns a string containing the keystore password.

setKeystorePassword

void setKeystorePassword(String newPassword)

Sets the keystore password to be used by the SSL configuration.

getKeystoreType

BrokerSSLConfigV2.KeystoreType getKeystoreType()

Returns the type of the keystore file.

setKeystoreType

void setKeystoreType(String newKeystoreType) throws BrokerSSLConfigException

crlType The type of the SSL CRL file. The type must be either PEM or DER. The default value of crlType is PEM.

newKeystoreType The type of the keystore file . The type must be KEYSTORE_TYPE_PKCS12, KEYSTORE_TYPE_PEM, or null. If the type is null, then the default keystore type, KEYSTORE_TYPE_PKCS12, is used.



Sets the type of the keystore file. Throws BrokerSSLConfigException if the value of newKeystoreType is not valid.

getSslProtocol

BrokerSSLConfigV2.SSLProtocol getSslProtocol()

Returns a string containing the SSL protocols allowed for the configuration.

setSslProtocol

void setSslProtocol(String newSslProtocol)

Sets the SSL protocol to be used by the configuration.

getTruststore

String getTruststore()

Returns the string containing the name of the SSL truststore file used by the SSL configuration.

setTruststore

void setTruststore(String newTruststore)

Sets the SSL truststore file to be used by the SSL configuration.

getTruststoreType

BrokerSSLConfigV2.TruststoreType getTruststoreType()

Returns the type of the truststore file used by the SSL configuration.

newSslProtocol The SSL protocol to be used. The valid values are:

SSL_PROTOCOL_ALL

SSL_PROTOCOL_SSLV3

SSL_PROTOCOL_TLSV1

null

If the value of newSslProtocol is null, then the default SSL protocol type, SSL_PROTOCOL_ALL is used.

When you specify SSL_PROTOCOL_ALL, the SSLv3 and TLSv1 protocols are allowed, but does not allow SSLv2 or earlier versions.

newTruststore The full path to the truststore file on the machine where the Broker Server is running.



setTruststoreType

void setTruststoreType(BrokerSSLConfigV2.TruststoreType newTruststoreType)

Sets the type of the truststore file to be used by the SSL configuration.

setTruststoreType

void setTruststoreType(String newTruststoreType) throws BrokerSSLConfigException

Sets the type of the truststore file to be used by the SSL configuration. Throws BrokerSSLConfigException if the value of newTruststoreType is not valid.

getVerifyDepth

int getVerifyDepth()

Returns an integer that specifies the maximum number of CA certificates allowed in a verification chain. If the certificate chain exceeds this number, then the connection is rejected.

setVerifyDepth

int setVerifyDepth(int newVerifyDepth) throws BrokerSSLConfigException

Sets the maximum number of CA certificates to be allowed in the verification chain. The default value is 9. Throws BrokerSSLConfigException if the value of newVerifyDepth is less than zero.

toString

String toString(int indent_level)

Returns the Broker's SSL configuration in a string format. The value of indent_level specifies the number of 4-space indents for the generated output.

BrokerSSLIdentity

class BrokerSSLIdentity extends java.lang.Object

newTruststoreType The BrokerSSLConfigV2.TruststoreType object to specify the type of the truststore file.

newTruststoreType The type of the truststore file . The type must be TRUSTSTORE_TYPE_PEM, TRUSTSTORE_TYPE_DIR, or null. If the type is null, then the default keystore type, TRUSTSTORE_TYPE_PEM is used.



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



BrokerServerClient.SSL_STATUS_ENABLED

BrokerServerClient.SSL_STATUS_ERROR

BrokerServerClient.SSL_STATUS_NOT_SUPPORTED

Constructors

BrokerSSLStatus

BrokerSSLStatus()

Creates an empty SSL status object.

BrokerSSLStatus

BrokerSSLStatus( int new_status, int new_level, String new_error_string)

Creates an SSL status object with the specified parameters.

BrokerTerritoryGatewayInfo

class BrokerTerritoryGatewayInfo extends java.lang.Object

This class is used to store configuration about a territory gateway. A gateway connects two distinct territories so that Broker clients in one territory can subscribe to and publish events to clients in the other territory. The gateway consists of two Brokers, each representing a distinct territory.


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.



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


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



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)



hide_gateway_broker If set to true, the gateway Broker's host and name as well as the is_local information, will be omitted.

hide_accessible_territories If set to true, the accessible_territories and is_complete information will be omitted.



BrokerTerritoryInfo

class BrokerTerritoryInfo extends java.lang.Object

This class is used to store configuration about a group of Brokers that make up a territory.


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


isLocalPublish

boolean isLocalPublish

Specifies whether document forwarding is enabled or disabled in the territory.

territory_name


The name of the territory.

Constructor

BrokerTerritoryInfo

BrokerTerritoryInfo()

Creates an empty territory information object.



Methods

toString

String toString()

Returns a string containing the territory information.

toString



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 Event description

TRACE_BROKER_ADDED A Broker is being added to a territory.

TRACE_BROKER_REMOVED A Broker is being removed from a territory.

TRACE_CLIENT_CONNECT A Broker client is being connected.

TRACE_CLIENT_CREATE A Broker client is being created.

TRACE_CLIENT_DESTROY A Broker client is being disconnected.

TRACE_CLIENT_DISCONNECT A Broker client is being destroyed.

TRACE_CLIENT_LOCK A Broker client queue is being locked.

TRACE_CLIENT_UNLOCK A Broker client queue is being unlocked.



Variables

app_name

String app_name

The name of the client application associated with the trace event. Only set for TRACE_CLIENT_CREATE and TRACE_CLIENT_DESTROY trace events. Set to null for all other trace events.

broker_host

String broker_host

For TRACE_BROKER_ADDED and TRACE_BROKER_REMOVED trace events, contains the name of the Broker Server being added to or removed from the territory.

For TRACE_EVENT_PUBLISH events, contains the name of the Broker Server that forwarded the event. Set to null if the event was not forwarded for any Broker.

For TRACE_EVENT_ENQUEUE, TRACE_EVENT_RECEIVE, and TRACE_EVENT_DROP events, contains the name of the Broker Server that enqueued, received, or dropped the event.

Set to null for all other events.

broker_name

String broker_name

For TRACE_BROKER_ADDED and TRACE_BROKER_REMOVED trace events, contains the name of the Broker being added to or removed from the territory.

TRACE_EVENT_DROP An event was dropped because a Broker client lacked the necessary permissions to receive the event. This may occur when client group permissions are changed.

TRACE_EVENT_ENQUEUE An event has been added to a Broker client's event queue by an administrative Broker Client.

TRACE_EVENT_DELETE An event has been deleted from a Broker client's queue by an administrative Broker Client.

TRACE_EVENT_INSERT An event has been inserted into a Broker client's queue.

TRACE_EVENT_PEEK An event has been peeked from a Broker client's queue.

TRACE_EVENT_PUBLISH An event has been published by a Broker client.

TRACE_EVENT_RECEIVE A Broker client has retrieved an event from its event queue.

TRACE_OTHER All other trace events.

Key Event description



For TRACE_EVENT_PUBLISH events, contains the name of the Broker that forwarded the event. Set to null if the event was not forwarded.

For TRACE_EVENT_ENQUEUE, TRACE_EVENT_RECEIVE, and TRACE_EVENT_DROP events, contains the name of the Broker that enqueued, received, or dropped the event.

Set to null for all other events.

client_group

String client_group

The name of the client group associated with the trace event. Only set for TRACE_CLIENT_CREATE and TRACE_CLIENT_DESTROY trace event. Set to null for all other trace events.

client_id

String client_id

For TRACE_CLIENT_CONNECT, TRACE_CLIENT_CREATE, TRACE_CLIENT_DESTROY, and TRACE_CLIENT_DISCONNECT events, this contains the identifier of the Broker client being created or destroyed.

For TRACE_EVENT_DROP, TRACE_EVENT_ENQUEUE, TRACE_EVENT_PUBLISH, and TRACE_EVENT_RECEIVE events, it contains the identifier of the client that published or received the Broker event.

dest_client_id

String dest_client_id

For TRACE_EVENT_DROP, TRACE_EVENT_ENQUEUE, TRACE_EVENT_PUBLISH, and TRACE_EVENT_RECEIVE events, this contains the identifier of the Broker client that is the recipient of a delivered event. Set to null if this trace event is associated with an event that is not being delivered.

encrypt_level

int encrypt_level

Set to one of the BrokerConnectionDescriptor.ENCRYPT_LEVEL_* values (see the webMethods Broker Client Java API Programmer’s Guide) which describes the encryption level of the client's connection. Only set for TRACE_CLIENT_CONNECT and TRACE_CLIENT_DISCONNECT trace events.

Set to null for all other trace events.

event_id

long event_id



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.


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.


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



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.



Methods

toString

String toString()

Returns a string containing the trace event in a human-readable format.


A API Exceptions

This appendix describes the exceptions that are unique to the webMethods Broker Java administrative API. Other possible exceptions are described in the webMethods Broker Client Java API Programmer’s Guide.

BrokerDependencyExceptionYour request to destroy a client group or an event type (without the force--destroy option) could not be completed because there are Broker clients that depend on the group or event type.

BrokerExistsExceptionYou have attempted to create a Broker with a name that is already being used by another Broker on the same Broker Server.

BrokerInClusterExceptionYou have attempted to destroy a Broker that is currently part of a cluster or you have attempted to add a Broker to a cluster when it is already a member of a cluster.

BrokerIncompatibleVersionExceptionYou have attempted to perform an operation on a Broker Server that is not supported. This results from the Broker Server in question having an earlier version number than the API that your client is using.

BrokerInTerritoryExceptionYou have attempted to destroy a Broker that is currently part of a territory or you have attempted to add a Broker to a territory when it is already a member of a territory.

BrokerInvalidAccessListExceptionThe Access Control List you specified is not valid.

BrokerInvalidBrokerNameExceptionThe Broker name you specified contains illegal characters. See the appendix in the webMethods Broker Client Java API Programmer’s Guide for details on naming rules.

BrokerInvalidClientGroupNameExceptionThe client group name you specified contains illegal characters. See the appendix in the webMethods Broker Client Java API Programmer’s Guide for details on naming rules.

BrokerInvalidLogConfigExceptionThe log configuration object you have specified is not valid.

BrokerInvalidClusterNameExceptionThe cluster name you specified when creating a cluster is not valid. See the appendix in the webMethods Broker Client Java API Programmer’s Guide for details on naming rules.


A API Exceptions

BrokerInvalidNameExceptionThe application name you specified when creating a Broker client is not valid. See the appendix in the webMethods Broker Client Java API Programmer’s Guide for details on naming rules.

BrokerInvalidTerritoryNameExceptionThe application name you specified when creating a territory is not valid. See the appendix in the webMethods Broker Client Java API Programmer’s Guide for details on naming rules.

BrokerNotInClusterExceptionYou have attempted to create or destroy a cluster gateway, but the Broker you have specified is not a member of any cluster.

You have specified a Broker that is not a member of any territory when attempting to add a Broker to or remove a Broker from a territory.

This error may also occur if you attempt to list the territories, territory gateways, shared event types, or territory statistics for a Broker that is not a member of any territory.

BrokerNotInTerritoryExceptionYou have attempted to create or destroy a territory gateway, but the Broker you have specified is not a member of any territory.

You have specified a Broker that is not a member of any territory when attempting to add a Broker to or remove a Broker from a territory.

This error may also occur if you attempt to list the territories, territory gateways, shared event types, or territory statistics for a Broker that is not a member of any territory.

BrokerUnknownBrokerNameExceptionYou have attempted to create or modify a territory gateway, but the remote half of the gateway has not yet been established and the remote Broker could not be found. You should start the remote Broker and attempt the operation again.

BrokerUnknownClusterExceptionYou have attempted to create or modify a cluster, but the cluster with the name you specified cannot be found.

This error might also occur if Broker did not find a gateway to the cluster you specified.

BrokerUnknownTerritoryExceptionYou have attempted to create or modify a territory, but the specified territory cannot be found.

This error might also occur if Broker did not find a gateway to the territory you specified.
