TIBCO Hawk® Console API Reference

Software Release 4.9 November 2010 Important Information SOME TIBCO EMBEDS OR BUNDLES OTHER TIBCO SOFTWARE. USE OF SUCH EMBEDDED OR BUNDLED TIBCO SOFTWARE IS SOLELY TO ENABLE THE FUNCTIONALITY (OR PROVIDE LIMITED ADD-ON FUNCTIONALITY) OF THE LICENSED TIBCO SOFTWARE. THE EMBEDDED OR BUNDLED SOFTWARE IS NOT LICENSED TO BE USED OR ACCESSED BY ANY OTHER TIBCO SOFTWARE OR FOR ANY OTHER PURPOSE. USE OF TIBCO SOFTWARE AND THIS DOCUMENT IS SUBJECT TO THE TERMS AND CONDITIONS OF A LICENSE AGREEMENT FOUND IN EITHER A SEPARATELY EXECUTED SOFTWARE LICENSE AGREEMENT, OR, IF THERE IS NO SUCH SEPARATE AGREEMENT, THE CLICKWRAP END USER LICENSE AGREEMENT WHICH IS DISPLAYED DURING DOWNLOAD OR INSTALLATION OF THE SOFTWARE (AND WHICH IS DUPLICATED IN LICENSE FILE) OR IF THERE IS NO SUCH SOFTWARE LICENSE AGREEMENT OR CLICKWRAP END USER LICENSE AGREEMENT, THE LICENSE(S) LOCATED IN THE “LICENSE” FILE(S) OF THE SOFTWARE. USE OF THIS DOCUMENT IS SUBJECT TO THOSE TERMS AND CONDITIONS, AND YOUR USE HEREOF SHALL CONSTITUTE ACCEPTANCE OF AND AN AGREEMENT TO BE BOUND BY THE SAME. This document contains confidential information that is subject to U.S. and international copyright laws and treaties. No part of this document may be reproduced in any form without the written authorization of TIBCO Software Inc. TIBCO, The Power of Now, TIBCO ActiveMatrix BusinessWorks, TIBCO Hawk, TIBCO Designer, TIBCO Rendezvous, TIBCO Enterprise Message Service, TIBCO Runtime Agent, TIBCO Administrator, TIBCO ActiveEnterprise and TIBCO Repository are either registered trademarks or trademarks of TIBCO Software Inc. in the United States and/or other countries. EJB, Java EE, J2EE, and all Java-based trademarks and logos are trademarks or registered trademarks of Sun Microsystems, Inc. in the U.S. and other countries. All other product and company names and marks mentioned in this document are the property of their respective owners and are mentioned for identification purposes only. THIS SOFTWARE MAY BE AVAILABLE ON MULTIPLE OPERATING SYSTEMS. HOWEVER, NOT ALL OPERATING SYSTEM PLATFORMS FOR A SPECIFIC SOFTWARE VERSION ARE RELEASED AT THE SAME TIME. SEE THE README FILE FOR THE AVAILABILITY OF THIS SOFTWARE VERSION ON A SPECIFIC OPERATING SYSTEM PLATFORM. THIS DOCUMENT IS PROVIDED “AS IS” WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT. THIS DOCUMENT COULD INCLUDE TECHNICAL INACCURACIES OR TYPOGRAPHICAL ERRORS. CHANGES ARE PERIODICALLY ADDED TO THE INFORMATION HEREIN; THESE CHANGES WILL BE INCORPORATED IN NEW EDITIONS OF THIS DOCUMENT. TIBCO SOFTWARE INC. MAY MAKE IMPROVEMENTS AND/OR CHANGES IN THE PRODUCT(S) AND/OR THE PROGRAM(S) DESCRIBED IN THIS DOCUMENT AT ANY TIME. THE CONTENTS OF THIS DOCUMENT MAY BE MODIFIED AND/OR QUALIFIED, DIRECTLY OR INDIRECTLY, BY OTHER DOCUMENTATION WHICH ACCOMPANIES THIS SOFTWARE, INCLUDING BUT NOT LIMITED TO ANY RELEASE NOTES AND "READ ME" FILES. Copyright © 1996-2010 TIBCO Software Inc. ALL RIGHTS RESERVED. TIBCO Software Inc. Confidential Information | iii Contents

Preface ...... xi Changes from the Previous Release of this Guide ...... xii Related Documentation ...... xiii TIBCO Hawk Documentation ...... xiii Other TIBCO Product Documentation ...... xiv Third-Party Documentation...... xiv Typographical Conventions ...... xv Connecting with TIBCO Resources ...... xvii How to Join TIBCOmmunity ...... xvii How to Access All TIBCO Documentation ...... xvii How to Contact TIBCO Support ...... xvii

Chapter 1 Overview ...... 1 Overview of the TIBCO Hawk Enterprise Monitor System ...... 2 How the TIBCO Hawk Console API Fits In ...... 4 Related TIBCO Hawk ...... 6 TIBCO Hawk Application Management Interface (AMI) API...... 6 TIBCO Hawk Security API ...... 6 TIBCO Hawk Configuration Object API ...... 7

Chapter 2 Concepts ...... 9 Structure of the TIBCO Hawk Console API ...... 10 Monitoring Operations ...... 11 The AgentInstance Class...... 12 Ensuring Each Agent Instance has a Unique ID ...... 13 Life Cycle of an AgentInstance Object ...... 13 Types of Monitoring Operations ...... 15 Agent-Alive Monitoring ...... 15 Microagent List Monitoring ...... 15 Rulebase List Monitoring ...... 16 Alert Monitoring ...... 16 Management Operations ...... 18 Microagent Descriptors ...... 19 Invoking Methods...... 20

TIBCO Hawk Console API Reference iv | Contents

Error Handling ...... 20 Subscribing to Method Results ...... 21 The MethodSubscription Class ...... 21 Error Handling ...... 22 Group Operations ...... 23 Lightweight Console ...... 24 MicroAgent Plug-in ...... 25

Chapter 3 's Checklist...... 27 Overview ...... 28 Install ...... 28 Code ...... 28 Compile ...... 28 Run ...... 28

Chapter 4 TIBCO Hawk Console API Class Structure...... 29 Key to the UML Diagrams ...... 30 Agent Monitoring Classes (Hawkeye) ...... 31 Agent Monitoring Classes (Cont)...... 32 Agent Management Classes...... 33 Agent Management Classes (Cont)...... 34

Chapter 5 Hawkeye Package Interfaces ...... 35 Monitoring Alert States with AlertMonitorListener...... 36 Determining Current Alert States and When they Change ...... 37 If Your Application Maintains Alerts ...... 38 Duplicate Alerts ...... 38 Retransmitted Alerts ...... 39 AgentMonitorListener ...... 40 AgentMonitorListener.onAgentAlive() ...... 41 AgentMonitorListener.onAgentExpired() ...... 42 AlertMonitorListener ...... 43 AlertMonitorListener.onAlertMonitorEvent()...... 44 AlertMonitorListener.onRetransmittedAlert() ...... 45 AlertState ...... 46 ErrorExceptionListener ...... 47 ErrorExceptionListener.onErrorExceptionEvent() ...... 48 ExceptionListener ...... 49 MicroAgentListMonitorListener ...... 50 MicroAgentListMonitorListener.onMicroAgentAdded()...... 51

TIBCO Hawk Console API Reference Contents | v

MicroAgentListMonitorListener.onMicroAgentRemoved() ...... 52 MonitorListener ...... 53 Method SummaryRuleBaseListMonitorListener ...... 56 RuleBaseListMonitorListener.onRuleBaseAdded() ...... 57 RuleBaseListMonitorListener.onRuleBaseRemoved() ...... 58 RuleBaseMonitorListener ...... 59 WarningExceptionListener ...... 60 WarningExceptionListener.onWarningExceptionEvent() ...... 61

Chapter 6 Hawkeye Package Classes ...... 63 AgentID ...... 64 AgentID.getDns() ...... 65 AgentID.getHawkDomain() ...... 66 AgentID.getName()...... 67 AgentInstance ...... 68 AgentInstance.get...() Accessors ...... 69 AgentInstance.isValid() ...... 71 AgentInstance.retransmitAlerts() ...... 72 AgentInstance.setUserData() ...... 74 AgentManager ...... 75 AgentManager.describe() ...... 76 AgentManager.getMicroAgentIDs() ...... 77 AgentManager.getMicroAgentIDs() ...... 78 AgentManager.groupOp()...... 79 AgentManager.initialize() ...... 80 AgentManager.invoke()...... 81 AgentManager.shutdown() ...... 83 AgentManager.subscribe() ...... 84 AgentMonitor ...... 86 AgentMonitor.add...() Methods ...... 89 AgentMonitor.initialize() ...... 90 AgentMonitor.remove...() Methods ...... 91 AgentMonitor.shutdown() ...... 92 AgentMonitorEvent ...... 93 AgentPlatform ...... 94 AgentVersion ...... 95 AlertMonitorEvent ...... 96 AlertMonitorEvent.get...() Accessors ...... 97 AlertMonitorEvent.RuleBaseEngineStateChanged() ...... 98 AlertMonitorEvent.RuleBaseStateChanged() ...... 99 ClearAlertEvent ...... 100

TIBCO Hawk Console API Reference vi | Contents

ClearAlertEvent.match() ...... 101 ErrorExceptionEvent ...... 102 ExceptionEvent ...... 103 MicroAgentListMonitorEvent ...... 104 MonitorEvent ...... 105 PostAlertEvent ...... 106 PostAlertEvent.get...() Accessors ...... 107 PostAlertEvent.isRetransmittedAlert() ...... 108 RuleBaseListMonitorEvent ...... 109 RuleBaseMonitorEvent ...... 110 RuleBaseStatus ...... 111 RuleBaseStatus.get...() Accessors ...... 112 TIBHawkConsole ...... 113 TIBHawkConsole.TIBHawkConsole() ...... 114 TIBHawkConsole.getAgentManager() ...... 116 TIBHawkConsole.getAgentMonitor() ...... 117 TIBHawkConsole.setCharacterEncoding() ...... 118 WarningExceptionEvent ...... 119

Chapter 7 Hawkeye Package Exception Classes ...... 121 ConsoleError ...... 122 ConsoleException ...... 123 ConsoleInitializationException ...... 124 ConsoleWarning ...... 125

Chapter 8 Talon Package Interfaces ...... 127 MicroAgentServer ...... 128 MicroAgentServer.describe() ...... 129 MicroAgentServer.getMicroAgentIDs() ...... 130 MicroAgentServer.invoke()...... 131 MicroAgentServer.subscribe() ...... 132 OpenData ...... 133 Subscription ...... 134 Subscription.cancel() ...... 135 Subscription.get...() Accessors ...... 136 SubscriptionHandler ...... 137 SubscriptionHandler.onData() ...... 138 SubscriptionHandler.onError() ...... 139 SubscriptionHandler.onErrorCleared()...... 140 SubscriptionHandler.onTermination()...... 141

TIBCO Hawk Console API Reference Contents | vii

Chapter 9 Talon Package Classes ...... 143 Agent ...... 144 CompositeData ...... 145 CompositeData.CompositeData()...... 146 CompositeData.get...() Accessors ...... 147 CompositeDataDescriptor ...... 148 CompositeDataDescriptor.CompositeDataDescriptor() ...... 149 CompositeDataDescriptor.isOpenData() ...... 150 DataDescriptor ...... 151 DataDescriptor.DataDescriptor() ...... 153 DataDescriptor.getDefault() ...... 155 DataDescriptor.getLegalValueChoices()...... 156 DataDescriptor.getValueChoices ...... 157 DataDescriptor.isOpenData() ...... 158 DataElement ...... 159 DataElement.DataElement()...... 160 MethodDescriptor ...... 161 MethodDescriptor.MethodDescriptor() ...... 163 MethodDescriptor.get...() Accessors ...... 165 MethodDescriptor.isAsync() ...... 166 MethodDescriptor.isOpenMethod()...... 167 MethodDescriptor.toFormattedString() ...... 168 MethodInvocation ...... 169 MethodInvocation.MethodInvocation() ...... 170 MethodSubscription ...... 171 MethodSubscription.MethodSubscription()...... 172 MethodSubscription.getInterval() ...... 174 MethodSubscription.isAsync() ...... 175 MicroAgentData ...... 176 MicroAgentData.MicroAgentData()...... 177 MicroAgentDescriptor ...... 178 MicroAgentDescriptor.MicroAgentDescriptor() ...... 179 MicroAgentDescriptor.get...() Accessors ...... 180 MicroAgentID ...... 182 MicroAgentID.MicroAgentID() ...... 183 TabularData ...... 184 TabularData.TabularData() ...... 185 TabularData.containsRow() ...... 186 TabularData.equals() ...... 187 TabularData.get...() Accessors ...... 188 TabularData.getRow()...... 189

TIBCO Hawk Console API Reference viii | Contents

TabularDataDescriptor ...... 190 TabularDataDescriptor.TabularDataDescriptor() ...... 191 TabularDataDescriptor.get...() Accessors ...... 192 TabularDataDescriptor.isOpenData()...... 193

Chapter 10 Talon Class Exception Classes ...... 195 MicroAgentException ...... 196 MicroAgentException.MicroAgentException() ...... 197 MicroAgentException.getException()...... 198

Chapter 11 MicroAgent Plug-in ...... 199 Introduction ...... 200 Running a Microagent in the TIBCO Hawk Agent ...... 201 Using an .hma Configuration File...... 202 Interface Summary...... 205 MicroAgent Plug-in Examples...... 206 AsyncDataHandler ...... 207 AsyncDataHandler.onData() ...... 208 AsyncDataHandler.onError() ...... 209 AsyncDataHandler.onErrorCleared() ...... 210 AsyncMethodHandler ...... 211 AsyncMethodHandler.startAsyncMethodSubscription()...... 212 AsyncMethodHandler.stopAsyncMethodSubscription()...... 213 ContainerEventListener ...... 214 ContainerEventListener.onInitial() ...... 215 ContainerEventListener.onMicroAgentAdded() ...... 216 ContainerEventListener.onMicroAgentRemoved()...... 217 MicroAgent ...... 218 MicroAgent.initializeMicroAgent() ...... 219 MicroAgent.describeMicroAgent() ...... 220 MicroAgent.thisMicroAgentAdded() ...... 221 MicroAgent.thisMicroAgentRemoved() ...... 222 MicroAgentContainer ...... 223 MicroAgentContainer.addMicroAgent() ...... 224 MicroAgentContainer.removeMicroAgent() ...... 225 MicroAgentContainer.addContainerEventListener() ...... 226 MicroAgentContainer.removeContainerEventListener()...... 227 ServiceMicroAgent ...... 228 ServiceMicroAgent.setMicroAgentContainer()...... 229 DynamicMicroAgent ...... 230 DynamicMicroAgent.invokeMethod() ...... 231

TIBCO Hawk Console API Reference Contents | ix

Index ...... 233

TIBCO Hawk Console API Reference x | Contents

TIBCO Hawk Console API Reference | xi Preface

This manual is intended for use by . It contains detailed descriptions of each class and method in the TIBCO Hawk® Console API, a set of Java interfaces that allow you to manage and interact with TIBCO Hawk agents and monitor alerts generated by these agents. This manual assumes you are familiar with TIBCO Rendezvous architecture and the concepts of system monitoring.

Topics

• Changes from the Previous Release of this Guide, page xii • Related Documentation, page xiii • Typographical Conventions, page xv • Connecting with TIBCO Resources, page xvii

TIBCO Hawk Console API Reference xii | Changes from the Previous Release of this Guide

Changes from the Previous Release of this Guide

This section itemizes the major changes from the previous release of this guide. Some sections have been updated with respect to TIBCO Hawk documentation defects.

TIBCO Hawk Console API Reference Preface | xiii

Related Documentation

This section lists documentation resources you may find useful.

TIBCO Hawk Documentation The following documents form the TIBCO Hawk documentation set: • TIBCO Hawk Installation and Configuration Read this book first. It contains step-by-step instructions for installing TIBCO Hawk software on various operating system platforms. It also describes how to configure the software for specific applications, once it is installed. An installation FAQ is included. • TIBCO Hawk Administrator’s Guide This manual includes basic descriptions of TIBCO Hawk concepts, instructions for using TIBCO Hawk Display, monitoring strategies with examples, a comprehensive FAQ, and a glossary. All books in the documentation set refer to features explained in this book. • TIBCO Hawk Plug-in for TIBCO Administrator Contains detailed descriptions of the TIBCO Hawk plug-ins accessed via TIBCO Administrator. • TIBCO Hawk Programmer’s Guide All programmers should read this manual. It covers the AMI protocol, AMI messages, the AMI Workbench development tool, and the TIBCO Hawk security framework and its classes. Programmers should then refer to the appropriate language reference for the AMI API. The TIBCO Hawk Application Management Interface (AMI) exposes internal application methods to TIBCO Hawk. • TIBCO Hawk AMI Reference Contains detailed descriptions of each datatype and function in the TIBCO Hawk C AMI API. • TIBCO Hawk AMI C++ Reference Contains detailed descriptions of each datatype and function in the TIBCO Hawk C++ AMI API. • TIBCO Hawk AMI Java Reference Contains detailed descriptions of each class and method in the TIBCO Hawk Java AMI API. • TIBCO Hawk Console API Reference Contains detailed descriptions of each class and method in the TIBCO Hawk Console API, a set of Java interfaces that allow you to manage and interact with TIBCO Hawk agents and monitor alerts generated by these agents. • TIBCO Hawk Configuration Object API Reference Contains detailed descriptions of each class and method in the TIBCO Hawk Configuration Object API. • TIBCO Hawk Methods Reference A reference to the microagents and methods used by a TIBCO Hawk Agent for system and application monitoring.

TIBCO Hawk Console API Reference xiv | Related Documentation

• TIBCO Hawk HTTP Adapter User’s Guide Contains information about performing discovery, monitoring of agent status, monitoring of agent alerts, method invocation, method subscription, and many more activities on TIBCO Hawk and third-party products. • TIBCO Hawk Enterprise Message Service Administrator Plug-in Microagent Reference Contains details about the microagent methods that are used to administer and monitor the TIBCO Enterprise Message Service server. • TIBCO Hawk Release Notes Read the release notes for a list of new and changed features. This document also contains lists of known issues and closed issues for this release.

Other TIBCO Product Documentation You may find it useful to read the documentation for the following TIBCO products: •TIBCO Rendezvous® — TIBCO Rendezvous Concepts — TIBCO Rendezvous Administration — TIBCO Rendezvous Configuration Tools • TIBCO Enterprise Message Service™ — TIBCO Enterprise Message Service Installation — TIBCO Enterprise Message Service User’s Guide • TIBCO Administator™ — TIBCO Administrator Installation Guide

Third-Party Documentation You may find the following third-party documentation useful. • The Java Language Specification by Gosling, Joy, and Steele

TIBCO Hawk Console API Reference Preface | xv

Typographical Conventions

The following typographical conventions are used in this manual.

Table 1 General Typographical Conventions Convention Use Many TIBCO products CAN be installed within the same directory. This directory is referenced in documentation as TIBCO_HOME. The value of TIBCO_HOME TIBCO_HOME depends on the operating system. For example, on Windows systems, the default value is C:\tibco. Incompatible products and multiple instances of the same product should be installed into different installation environments.

CONFIG_FOLDER A TIBCO configuration folder stores configuration data generated by TIBCO products. Configuration data can include sample scripts, session data, configured binaries, logs, and so on. This folder is referenced in documentation as CONFIG_FOLDER. TIBCO Hawk installs into a directory within . This directory is HAWK_HOME referenced in documentation as HAWK_HOME. The value of HAWK_HOME depends on the operating system. For example on Windows systems, the default value is C:\tibco\hawk\4.9.

code font Code font identifies commands, code examples, filenames, pathnames, and output displayed in a command window. For example:

Use MyCommand to start the foo process.

bold code font Bold code font is used in the following ways:

• In procedures, to indicate what a user types. For example: Type admin. • In large code samples, to indicate the parts of the sample that are of particular interest. • In command syntax, to indicate the default parameter for a command. For example, if no parameter is specified, MyCommand is enabled: MyCommand [enable | disable]

TIBCO Hawk Console API Reference xvi | Typographical Conventions

Table 1 General Typographical Conventions (Cont’d) Convention Use

italic font Italic font is used in the following ways: • To indicate a document title. For example: See TIBCO BusinessWorks Concepts. • To introduce new terms For example: A portal page may contain several portlets. Portlets are mini-applications that run in a portal. • To indicate a variable in a command or code syntax that you must replace. For example: MyCommand pathname

Key Key name separated by a plus sign indicate keys pressed simultaneously. For combinations example: Ctrl+C. Key names separated by a comma and space indicate keys pressed one after the other. For example: Esc, Ctrl+Q.

The note icon indicates information that is of special interest or importance, for example, an additional action required only in certain circumstances.

The tip icon indicates an idea that could be useful, for example, a way to apply the information provided in the current section to achieve a specific result.

The warning icon indicates the potential for a damaging situation, for example, data loss or corruption if certain steps are taken or not taken.

TIBCO Hawk Console API Reference Preface | xvii

Connecting with TIBCO Resources

How to Join TIBCOmmunity TIBCOmmunity is an online destinaton for TIBCO customers, partners, and resident experts—a place to share and access the collective experience of the TIBCO community. TIBCOmmunity offers forums, blogs, and access to a variety of resources. To register, go to http://www.tibcommunity.com.

How to Access All TIBCO Documentation After you join TIBCOmmunity, you can access the documentation for all supported product versions here: http://docs.tibco.com/TibcoDoc

How to Contact TIBCO Support For comments or problems with this manual or the software it addresses, please contact TIBCO Support as follows. • For an overview of TIBCO Support, and information about getting started with TIBCO Support, visit this site: http://www.tibco.com/services/support • If you already have a valid maintenance or support contract, visit this site: https://support.tibco.com Entry to this site requires a user name and password. If you do not have a user name, you can request one.

TIBCO Hawk Console API Reference xviii | Connecting with TIBCO Resources

TIBCO Hawk Console API Reference | 1

Chapter 1 Overview

The TIBCO Hawk Console API is a Java language interface for writing programs that can perform monitoring and management of TIBCO Hawk agents. It is an integral part of the TIBCO Hawk Enterprise Monitor system and is used by several of its components. It provides all the facilities required to perform discovery, monitoring of agent-alive status, monitoring of agent alerts, and the monitoring of agent configuration changes. It also allows you interact with agents and their managed objects through remote method invocations on microagents. This chapter provides a brief overview of the major components of the TIBCO Hawk Enterprise Monitor and how the TIBCO Hawk Console API relates to them.

Topics

• Overview of the TIBCO Hawk Enterprise Monitor System, page 2 • How the TIBCO Hawk Console API Fits In, page 4 • Related TIBCO Hawk APIs, page 6

TIBCO Hawk Console API Reference 2 | Chapter 1 Overview

Overview of the TIBCO Hawk Enterprise Monitor System

The TIBCO Hawk Enterprise Monitor is a scalable tool for monitoring and management of distributed systems. It consists of agents running on nodes throughout the network. These agents autonomously monitor various system and application parameters and take actions based on their values. Rulebases, authored by users, direct the monitoring behavior and the actions to take. These rulebases are easy to build and can be very simple or very complex. The rules get their data from microagents. Microagents represent managed entities such as the operating system's subsystems, log files, event logs, or applications. Each microagent runs within an agent, but the managed application it represents can be a separate process. Each agent can therefore be considered a collection of rulebases and microagents. The TIBCO Hawk Display is a console application that displays the status of all agents. It is used to view alerts, interact with agents and their microagents, and edit rulebases and other configuration objects. The status of the system can be viewed in either a node-centric or rulebase/application-centric manner. Color-coded alert conditions direct the user's attention to problems. The TIBCO Hawk Event Service is another console application that listens to all monitoring events and logs them to a file or a . TIBCO Hawk uses TIBCO Rendezvous is the communication mechanism between the microagents and the primary AMI session. Agents communicate with the Console applications using either TIBCO Rendezvous or TIBCO Enterprise Messaging Service. The following figure gives an overview of the TIBCO Hawk system architecture.

TIBCO Hawk Console API Reference Overview of the TIBCO Hawk Enterprise Monitor System | 3

Figure 1 TIBCO Hawk System Architecture

TIBCO Hawk Display

TIBCO Rendezvous Application AMI

TIBCO Hawk Agent Managed Node Agent publish/ subscribe TIBCO Messaging TIBCO publish/ TIBCO Hawk Display subscribe

Application API AMI TIBCO Rendezvous TIBCO Hawk Agent Managed Node Adapter or Gateway

TIBCO Hawk Agent TIBCO Hawk Event Service Managed Node

TIBCO Hawk Console API Reference 4 | Chapter 1 Overview

How the TIBCO Hawk Console API Fits In

The TIBCO Hawk Console API allows you to write programs that can monitor the alerts generated by TIBCO Hawk agents and perform management operations on their microagents. Applications using this API can be referred to as console applications. Both the TIBCO Hawk Display and the TIBCO Hawk Event Service use the TIBCO Hawk Console API to monitor or manage agents, or both. They are thus both good examples of the types of applications that can be built with this interface. Applications built with the Console API can monitor every node within a given TIBCO Hawk domain. That is why you'll typically find only one instance of the TIBCO Hawk Display or Event Service running. However, additional instances of console applications can run simultaneously on multiple nodes in the network with little or no additional network impact.

The TIBCO Hawk Console API does not provide facilities for the creation of rulebases.

Monitoring Component The monitoring component of the TIBCO Hawk Console API provides events that notify your application when: • Agents are discovered •Agents expire • Alerts and clears are generated by an agent's rules engine • An agent's list of microagents changes • An agent's list of rulebases changes

Management Component The management component allows you to interact with an agent's microagents by: • Invoking their methods to return management data or perform management functions • Subscribing to their management data in a way that produces an updating data stream of management information

TIBCO Hawk Console API Reference How the TIBCO Hawk Console API Fits In | 5

• Performing group operations on multiple Microagents across the network simultaneously

TIBCO Hawk Console API Reference 6 | Chapter 1 Overview

Related TIBCO Hawk APIs

The following APIs are available and documented separately. References to the appropriate document are given in the following sections.

TIBCO Hawk Application Management Interface (AMI) API The Application Management Interface (AMI) is a protocol based on TIBCO Rendezvous which is used to instrument an application in a way that allows it to be monitored and managed through a TIBCO Hawk agent. The AMI API simplifies this instrumentation process by shielding the user from the details of the protocol and eliminating the need to understand the TIBCO Rendezvous API to implement it. AMI allows an application to be instrumented in such a way that causes it to be represented as a microagent, typically in the agent collocated on same node as the application. Applications use AMI to expose methods that are used to perform management operations or to collect management data. These methods are mapped into methods of the corresponding microagent and can then be used in rulebase monitoring or accessed directly from the TIBCO Hawk Display or the Console API. AMI is also used to build adapters to other management systems such as SNMP (Simple Network Management Protocol), which allows them to be represented as microagents. Thus, AMI effectively provides a facility for adding microagents to an agent. In contrast, the Console API is used to interact with an agent and its microagents. For more information on this interface, see the TIBCO Hawk Programmer’s Guide, and the appropriate language reference for your environment: TIBCO Hawk AMI C Reference, TIBCO Hawk AMI C++ Reference, or TIBCO Hawk AMI Java Reference.

TIBCO Hawk Security API The TIBCO Hawk Security API is used to build security plug-in modules used for secure interactions between agent and console. The security mechanism actually involves two modules, one that is used by the agent and another that is used by the console. If you write console applications using the Console API that will operate in a secure TIBCO Hawk environment, you will have to have access to the console-side security plug-in class in order to perform management operations on agents. This is the same class that the TIBCO Hawk Display requires in order to manage agents in a secure environment.

TIBCO Hawk Console API Reference Related TIBCO Hawk APIs | 7

For more information on this interface, see the TIBCO Hawk Programmer’s Guide.

TIBCO Hawk Configuration Object API The TIBCO Hawk Configuration Object API is a Java language interface for writing rulebases, which perform the monitoring activities. The Configuration Object API provides classes to define rules, tests and actions. Instances of these classes are strung together to define a new rulebase. For more information on this interface, see the TIBCO Hawk Configuration Object API Reference.

TIBCO Hawk Console API Reference 8 | Chapter 1 Overview

TIBCO Hawk Console API Reference | 9

Chapter 2 Concepts

This chapter provides some background information on using the classes.

Topics

• Structure of the TIBCO Hawk Console API, page 10 • Monitoring Operations, page 11 • The AgentInstance Class, page 12 • Types of Monitoring Operations, page 15 • Management Operations, page 18 • Microagent Descriptors, page 19 • Invoking Methods, page 20 • Subscribing to Method Results, page 21 • Group Operations, page 23 • Lightweight Console, page 24 • MicroAgent Plug-in, page 25

TIBCO Hawk Console API Reference 10 | Chapter 2 Concepts

Structure of the TIBCO Hawk Console API

The TIBCO Hawk Console API is partitioned along the functional lines of monitoring and management. At the root is the TIBHawkConsole class from which you can access the AgentMonitor and AgentManager, which encompass the monitoring and management facilities of the API.

TIBCO Hawk Console API Reference Monitoring Operations | 11

Monitoring Operations

The TIBCO Hawk Console API allows you to monitor all agents simultaneously from a single program. For each agent, the API's monitoring capabilities can be decomposed into four areas: • Agent-Alive Monitoring • Microagent List Monitoring • Rulebase List Monitoring • Alert Monitoring All monitoring is performed using event notification. Listeners are registered with the AgentMonitor for the type of monitoring required and the relevant status messages are delivered as events when they are detected. A registered listener for a particular type of event will receive notifications for all monitored agents that generate that event. For example, registering a AgentMonitorEventLister with the console will allow it to receive AgentMonitorEvents for all agents known to the console, thus allowing it to track the alive or expired status of every agent.

TIBCO Hawk Console API Reference 12 | Chapter 2 Concepts

The AgentInstance Class

Common to all monitoring events, and that which relates them to each other, is the agent instance they pertain to. This agent instance is represented in the TIBCO Hawk Console API by the AgentInstance class. The following definitions and discussion describe this class, the related AgentID class, and their role in monitoring.

Real Agent ID The real agent ID specifies the attributes of a real agent process that are used to uniquely identify it. These attributes are • Agent name •DNS name • TIBCO Hawk domain name.

Real Agent Instance The real agent instance is an instantiation of a real agent; the actual agent process running on some machine in the network. If a real agent is restarted, the new process represents a new real agent instance. Real agent instances have a life span that begins with the starting of an agent process and ends with its termination.

Console Agent ID The console agent ID is the representation of a real agent ID in the console. It is essentially equivalent to the real agent ID.

Console agent IDs are represented by the AgentID class.

Console Agent Instance The console agent instance is a representation of an instance of a real agent from the console's perspective. A console agent instance is associated with real agent instances but the two may have different life spans. The console agent instance's life as an object begins when the console discovers a real agent instance and ends when that real agent instance can no longer be communicated with, for example, when the agent process dies, is restarted, or a when some other problem exists that prevents communication. When communication is re-established, either

TIBCO Hawk Console API Reference The AgentInstance Class | 13

because the real agent was restarted or communication to the original real agent instance was restored, a new console agent instance is created to represent that connection. It is therefore possible for a single real agent instance to be represented by different console agent instances over the course of its life span.

Console agent instances are represented by the AgentInstance class.

Ensuring Each Agent Instance has a Unique ID In order for the TIBCO Hawk system to function correctly, every concurrently running real agent instance must have a unique real agent ID. The console will attempt to detect violations of this condition and produce a warning. However, this may not be detectable in all circumstances and so the system administrator must insure that every agent has a unique agent ID. A real agent ID, and thus a console agent ID, is determined by the combination of three attributes: • Agent name •DNS name • TIBCO Hawk domain name. If a console client is interested in tracking agent status across real agent instances or console agent instances then it may do so using the console agent ID, that is, the AgentID class. If a real agent is restarted several times (without changing its ID attributes) then this will result in the creation of several distinct instances of AgentInstance in the console. These different instances, however, will all have equal AgentID values to reflect the fact that they all relate to the same logical agent. Note that these multiple instances of AgentInstance will never be referenced simultaneously by the console. This is because the console will never hold two AgentInstance objects with equal AgentID attributes at any one time.

Life Cycle of an AgentInstance Object

As mentioned, the AgentInstance is used in all monitoring events to associate an event with a particular agent. How instances of AgentInstance objects are created and released by the console illustrates the relationship that agent-alive monitoring has with the other three types of monitoring. The life cycle of an AgentInstance object within the console is as follows:

1. An AgentInstance object is created when the console discovers a real agent instance. The console maintains a reference to this object and also delivers it in an event which signals "agent-alive." No other events will be delivered by the console for a particular AgentInstance before its agent-alive event.

TIBCO Hawk Console API Reference 14 | Chapter 2 Concepts

2. Status events pertaining to the monitoring of rulebase lists, microagent lists, and alerts are then generated and delivered (if a listener has been registered for them) as the relevant conditions are detected. Each will contain an AgentInstance object which was previously delivered in the alive-alive event. 3. When communication with the corresponding real agent instance is lost, the AgentInstance object is marked invalid and an "agent-expired" event is delivered for it. At this point, the console releases its reference to this AgentInstance object and no further events are ever associated with it again.

TIBCO Hawk Console API Reference Types of Monitoring Operations | 15

Types of Monitoring Operations

This section contains more detail on each type of monitoring: • Agent-Alive Monitoring • Microagent List Monitoring • Rulebase List Monitoring • Alert Monitoring

Agent-Alive Monitoring The most basic type of monitoring is the monitoring of agent existence. This is achieved by registering an AgentMonitorListener with the AgentMonitor. When you register an AgentMonitorListener, it will receive one agent-alive event for every agent the console can detect. An agent-alive event is actually represented by the delivery of an AgentMonitorEvent to the onAgentAlive() method of the listener. This event contains a reference to an AgentInstance object which identifies which agent it pertains to. As new agents appear in the network, new agent-alive events will be generated to identify them. When the console is no longer able to communicate with an agent, it will issue an agent-expired event for that agent. This is performed by delivering a AgentMonitorEvent to the onAgentExpired() method of the listener. As before, this event contains a reference to an AgentInstance object which identifies which agent it pertains to. The console can lose communication with an agent for several reasons, for example if the agent process is no longer running, the machine it was running on has crashed, or because of a problem in the underlying communications infrastructure such as a network outage.

Microagent List Monitoring Each agent contains a collection of objects called microagents. Microagents have methods through which monitoring and management is performed. Microagents represent managed entities such as the operating system's subsystems, log files, event logs, or applications. A newly launched application instrumented with AMI will dynamically appear as a microagent on its managing agent (by default, the one located on the same processor). When the instrumented application terminates, the corresponding microagent will also be removed. Microagent list monitoring is used to track the dynamic list of microagents in an agent. Events are delivered when microagents are added and removed.

TIBCO Hawk Console API Reference 16 | Chapter 2 Concepts

To perform this type of monitoring you simply register a MicroAgentListMonitorListener with the AgentMonitor. Events of type MicroAgentListMonitorEvent are then delivered to either the onMicroAgentAdded() or onMicroAgentRemoved() method of the listener. The event contains an AgentInstance object, which identifies the agent, and a MicroAgentID object, which identifies the microagent.

Rulebase List Monitoring Rulebases direct the monitoring activities of an agent. Each rulebase is a collection of rules which are usually grouped together to monitor an application or system resource. An agent may have more than one loaded rulebase and this list can change dynamically. Rulebase list monitoring is structurally similar to microagent list monitoring. It is used to monitor the dynamically changing list of rulebases that are loaded on an agent. To perform this type of monitoring you register a RuleBaseListMonitorListener with the AgentMonitor. Events of type RuleBaseListMonitorEvent are then delivered to either the onRuleBaseAdded() or onRuleBaseRemoved() method of the listener. The event contains an AgentInstance object, which identifies the agent, and a RuleBaseStatus object, which is used to identify the rulebase being added or removed.

Alert Monitoring One of the actions a rulebase can take is to generate an alert, which is usually done to signal that a problem condition has been detected. Alerts contain a state, to indicate the problem severity, and text, which provides the problem description. If the alert condition, as defined by the rulebase, ceases to exist, the rulebase will generate a clear against that alert. Every alert is associated with a particular rulebase and every rulebase is associated with a particular agent. (Technically, rulebases are said to be associated with the RuleBaseEngine microagent instance registered with that agent, therefore the association with the agent is indirect.) The alert state of a rulebase will always be highest alert state of all the active (non-cleared) alerts associated with it. The alert state of an agent (or its RuleBaseEngine microagent) is the highest alert state of any of its currently loaded rulebases. Therefore, alerts and clears can potentially change the state of the rulebase and agent that generated them.

TIBCO Hawk Console API Reference Types of Monitoring Operations | 17

Alert monitoring is performed by registering an AlertMonitorListener with the AgentMonitor. Alerts and clears generated by an agent are detected by the console and delivered as AlertMonitorEvent objects to the listener. Since AlertMonitorEvent is an abstract class, one of its concrete subclasses is delivered: PostAlertEvent for alerts and ClearAlertEvent for clears.

Every AlertMonitorEvent contains flags that indicate whether it caused a change in the state of the RuleBaseEngine or the rulebase it is associated with. It also holds the current states of those objects after taking into account the current event. Other attributes include an alert ID, which uniquely identifies an alert, and the time the event was generated.

Because AlertMonitorEvent extends AgentMonitorEvent, it also has an AgentInstance attribute to identify the agent that generated the event.

The PostAlertEvent class extends AlertMonitorEvent and adds the state of the alert and the alert text. The ClearAlertEvent class extends AlertMonitorEvent and adds the reason-cleared text. This string identifies the reason the alert was cleared. All alert states are represented as integer values that are mapped using the AlertState interface. A PostAlertEvent with a state of AlertState.NO_ALERT is also called a notification.

For more information on how AlertMonitorEvents may be used, see Monitoring Alert States with AlertMonitorListener on page 36.

TIBCO Hawk Console API Reference 18 | Chapter 2 Concepts

Management Operations

Management functions are performed by invoking management operations on microagents. As described in Microagent List Monitoring on page 15, each agent contains a collection of objects called microagents. Microagents have methods through which all monitoring and management is performed. Microagents represent managed entities such as the operating system's subsystems, log files, event logs, applications, and even the agent itself.

The AgentManager class is used to interact with microagents. An instance of this class is obtained by invoking the getAgentManager() method of the TIBHawkConsole class. The first step in interacting with a microagent is to obtain its descriptor. This descriptor enumerates the available methods and describes their signature and their return types. With this information you can then invoke methods and subscribe to method results for an individual microagent. You can also perform a group operation that simultaneously performs a method invocation on multiple instances of the same microagent across multiple agents.

TIBCO Hawk Console API Reference Microagent Descriptors | 19

Microagent Descriptors

Descriptors are represented by the MicroAgentDescriptor class. They are obtained by invoking the describe() method of the AgentManager class. A MicroAgentDescriptor fully describes a microagent. It contains a list of MethodDescriptor objects that describe each available method and all that is needed to invoke them. The methods of a microagent are divided into three categories depending on their impact. These categories are enumerated by the following static variables of the MethodDescriptor class:

• IMPACT_ACTION: Methods of type IMPACT_ACTION take some action that can potentially change the state of the managed object represented by the microagent.

• IMPACT_INFO: Methods of type IMPACT_INFO simply retrieve some information in a manner that does not change the state of the managed object.

• IMPACT_ACTION_INFO: Methods of type IMPACT_ACTION_INFO return data but may also change the sate of the managed object.

The describe() method of the AgentManager requires an argument of type MicroAgentID. There are two general ways to obtain MicroAgentID objects:

• If your application is also performing monitoring then the MicroAgentIDs for microagents loaded on a particular agent can be obtained from the method AgentInstance.getStatusMicroAgents(). A registered MicroAgentListMonitor object also receives MicroAgentIDs in the events delivered to it.

•The method AgentManager.getMicroAgentID() can also be used to obtain MicroAgentID objects. It takes a microagent name as its argument and returns an array of all microagents of that name that are currently loaded on all agents the console can communicate with. This method blocks for a period of time while it queries the agents on the network. A second version of this method accepts an integer that indicates the minimum number of desired microagent ids in the return. This method generally returns more quickly than the first version if the minimum number specified is less than or equal to the actual number of matching microagents on the network.

TIBCO Hawk Console API Reference 20 | Chapter 2 Concepts

Invoking Methods

Microagent methods are invoked using the invoke() method of the AgentManager. This method takes a MicroAgentID and a MethodInvocation object. The MicroAgentID may be obtained as described in Microagent Descriptors on page 19. The MethodInvocation can be constructed using the data provided in the microagent descriptor.

Method invocations return an instance of the MicroAgentData class, which acts as a container for transmitting invocation results. MicroAgentData objects contain source and data attributes. The source attribute is a MicroAgentID object identifying the source of the data. The data attribute contains the actual method invocation results.

Error Handling Two general types of errors can occur with method invocations: 1. During the delivery of a method invocation to, or the results back from, a microagent. This condition will cause the invoke() method to throw a MicroAgentException. 2. During the invocation of the method on the microagent itself. This condition will cause this method to deliver a MicroAgentException in the data field of the MicroAgentData return. Thus, a successful method invocation is one that doesn't throw an exception and does not deliver a MicroAgentException in the data field of its MicroAgentData return.

If the method invocation is successful, the data field of its MicroAgentData return will contain the method's return value or null if the method doesn't return a value.

TIBCO Hawk Console API Reference Subscribing to Method Results | 21

Subscribing to Method Results

The AgentManager also allows you to register a subscription for microagent methods with its subscribe() method. Registering for a subscription is analogous to registering for an event. It results in a continuous stream of MicroAgentData return values from the method being subscribed to. This data is asynchronously delivered to a SubscriptionHandler object supplied during registration.

In addition to a SubscriptionHandler, the subscribe() method of AgentManager requires a MicroAgentID, to identify the target, and a MethodSubscription object.

The MethodSubscription Class

The MethodSubscription class extends the MethodInvocation class. A MethodSubscription should be constructed in accordance with the MethodDescriptor of the target method.

Registering a subscription returns a Subscription object that can be used to cancel the subscription and to examine how the subscription was created Only methods that return data should be subscribed to. This includes methods of type IMPACT_INFO and IMPACT_ACTION_INFO.

Synchronous and Asynchronous Method Subscriptions

You can use either of two constructors to build a MethodSubscription, depending on whether you are creating a subscription for a synchronous or asynchronous method. The MethodDescriptor for a method indicates whether the method is synchronous or asynchronous. An asynchronous method is analogous to an event source. Listeners that subscribe to an asynchronous method will receive the method's declared return value each time a particular event occurs.

The MethodSubscription constructor for synchronous method subscriptions requires an interval parameter. It is used to specify a desired subscription service rate. Subscriptions made of synchronous methods will use this value as a hint to determine how often to deliver data to service a subscription. Most microagents will usually enforce a minimum rate, which will be used if the supplied value is below their minimum.

The MethodSubscription constructor for asynchronous method subscriptions does not accept an interval parameter. Asynchronous methods deliver data at a rate determined by the microagent, typically, whenever it is available.

TIBCO Hawk Console API Reference 22 | Chapter 2 Concepts

Error Handling Two general types of errors can occur with subscriptions: 1. During the registration of the subscription. This condition will cause the AgentManager.subscribe() method to throw a MicroAgentException. 2. During the servicing of the subscription These errors are delivered to the SubscriptionHandler.

TIBCO Hawk Console API Reference Group Operations | 23

Group Operations

Group operations are performed with the groupOp() method of the AgentManager. They are very similar to method invocations. The difference is that they require an array of MicroAgentID targets and return an array of MicroAgentData values. A group operation effectively performs a method invocation simultaneously on all of the specified target microagents. It is useful for affecting a group of microagents in a single operation.

TIBCO Hawk Console API Reference 24 | Chapter 2 Concepts

Lightweight Console

By default, the console monitors and can communicate with every agent in a given TIBCO Hawk domain. If, however, you are building an application that needs to interact with only a single agent, you can initialize the console in such a way that limits its communication to just that agent. This results in a lightweight console instance that uses fewer resources.

Creating a Instantiating a lightweight console involves constructing a TIBHawkConsole Lightweight object with a fully qualified hawkDomain parameter. ((See TIBHawkConsole on Console page 113.) A fully qualified hawkDomain narrows down the domain to a single agent and contains the three parts that uniquely identify an agent, in a dot-separated format: .. is what would be used as the hawkDomain parameter of the TIBHawkConsole constructor if you were instantiating a console that communicates with all agents. If an agent is configured without a hawkDomain specification, it uses the value "default". • should match the agentDNS (also called agent domain) parameter with which the agent was configured. If the agent was not configured with an agentDNS, it uses the value "none". • must match the agent name. If not set, this defaults to the hostname the agent is running on. See The AgentInstance Class on page 12 for more information

Using the Dot and None of the three elements may contain the dot '.' character. The dot is used as a Underscore separator in a fully qualified hawkDomain. If any of the three components require Characters a dot (agentDNS typically does), replace all occurrences with the underscore '_' character. The agent automatically performs this translation on its end. For example, if an agent is configured with the following values:

• hawkDomain = testDomain

•agentDNS = myfirm.com (note the dot in the name)

•agentName = host1 the fully qualified hawk domain is: testDomain.myfirm_com.host1

TIBCO Hawk Console API Reference MicroAgent Plug-in | 25

MicroAgent Plug-in

The COM.TIBCO.hawk.agent.nest package is used to write TIBCO Hawk microagents that run inside the agent. To run as a microagent in the TIBCO Hawk agent, an object must implement either the MicroAgent or ServiceMicroAgent interface. See MicroAgent Plug-in on page 199 for details. Note that this package is dependent on the COM.TIBCO.hawk.console.talon package.

TIBCO Hawk Console API Reference 26 | Chapter 2 Concepts

TIBCO Hawk Console API Reference | 27

Chapter 3 Programmer's Checklist

The TIBCO Hawk Java API provides a set of class packages implemented by the TIBCO Hawk AMI, to be used as components in building applications for the TIBCO Hawk monitoring system and invoking methods on the objects implemented by the classes.

Topics

• Overview, page 28

TIBCO Hawk Console API Reference 28 | Chapter 3 Programmer's Checklist

Overview

Install Install the latest TIBCO Hawk software and TIBCO Rendezvous software releases. We recommend using Java 1.3.1 to compile and run your application using Console API.

Code Your application using Console API source code file must contain the following imports:

import COM.TIBCO.hawk.console.hawkeye.*; import COM.TIBCO.hawk.talon.*;

Compile While compiling your Console API Java application, your CLASSPATH must include console.jar and talon.jar from the TIBCO Hawk Java directory. If using TIBCO EMS, your CLASSPATH must additionally include tibrvjms.jar, jms.jar, tibjms.jar, and tibcrypt.jar. These additional jar files have to be placed before the tibrvj.jar file. If using JRE 1.3.1 and TIBCO EMS, the jaxp.jar from the TIBCO EMS Java client must also be included.

Run

While running your AMI Java application, your CLASSPATH must include console.jar and talon.jar from the TIBCO Hawk Java directory and tibrvj.jar from the TIBCO Rendezvous /lib directory. If using TIBCO EMS, your CLASSPATH must additionally include tibrvjms.jar, jms.jar, tibjms.jar, and tibcrypt.jar. These additional jar files have to be placed before the tibrvj.jar file. If using JRE 1.3.1 and TIBCO EMS, the jaxp.jar from the TIBCO EMS Java client must also be included.

TIBCO Hawk Console API Reference | 29

Chapter 4 TIBCO Hawk Console API Class Structure

This chapter contains UML diagrams showing the structure of the following two packages:

COM.TIBCO.hawk.hawkeye: classes used to monitor agents

COM.TIBCO.hawk.talon: classes used to manage agents

Topics

• Key to the UML Diagrams, page 30 • Agent Monitoring Classes (Hawkeye), page 31 • Agent Management Classes, page 33

TIBCO Hawk Console API Reference 30 | Chapter 4 TIBCO Hawk Console API Class Structure

Key to the UML Diagrams

These class diagrams use a subset of UML notation. Here is a brief key: Classes and their methods are shown in rectangles:

Class Name method1(argName:type,…):methReturnType method2(argName:type,…):methReturnType ...

Some methods and argument names are omitted for clarity. A third part, between the class name and methods, may be used for class variables. Underlined members are static. Comments are shown in a rectangle with a turned down corner. A dotted line shows what the comment applies to.

Associations Associations are indicated with lines:

Inheritance

Superclass Subclass

Interface Implementing Class

Navigation

ClassA ClassB

An instance of Class A can be referenced from an instance of Class B Aggregation

ClassA ClassB

Composite aggregation. An instance of ClassA contains an aggregation of instances of ClassB. These instances of ClassB belong to only one composite at a time.

TIBCO Hawk Console API Reference Agent Monitoring Classes (Hawkeye) | 31

Agent Monitoring Classes (Hawkeye)

TIBCOHawkConsole <> TIBCOHawkConsole(licenseFile:String, hawkDomain:String, rvService:String, rvNetwork:String, rvDaemon:String) AgentManager <> getAgentManager():AgentManager getAgentMonitor():AgentMonitor

AgentMonitor initialize() add/removeAgentMonitorListener(:AgentMonitorListener) add/removeMicroAgentListMonitorListener(:MicroAgentListMonitorListener) add/removeRuleBaseListMonitorListener(:RuleBaseListMonitorListener) add/removeAlertMonitorListener(:AlertMonitorListener) <> add/removeErrorExceptionListener(:ErrorExceptionListener) MonitorListener addremove/WarningExceptionListener(:WarningExceptionListener) shutdown()

<> AgentMonitorListener onAgentAlive(:AgentMonitorEvent) onAgentExpired(:AgentMonitorEvent)

<> MicroAgentListMonitorListener onMicroAgentAdded(:MicroAgentListMonitorEvent) onMicroAgentRemoved(:MicroAgentListMonitorEvent)

<> RuleBaseMonitorListener

<> RuleBaseListMonitorListener onRuleBaseAdded(:RuleBaseListMonitorEvent ) onRuleBaseRemoved(:RuleBaseListMonitorEvent)

<> AlertMonitorListener onAlertMonitorEvent(:AlertMonitorEvent )

onRetransmittedAlert(:AlertMonitorEvent)

<> ExceptionListener

<> ErrorExceptionListener onErrorExceptionEvent(:ErrorExceptionEvent )

<> WarningExceptionListener

onWarningExceptionEvent(:WarningExceptionEvent )

TIBCO Hawk Console API Reference 32 | Chapter 4 TIBCO Hawk Console API Class Structure

Agent Monitoring Classes (Cont)

MonitorEvent AgentInstance getAgentInstance():AgentInstance getAgentID():AgentID getAgentPlatform():AgentPlatform AgentMontorEvent getAgentVersion():AgentVersion getCluster():String 0 MicroAgentListMonitorEvent getIPAddress():String . COM.TIBCO.hawk.talon. getRuleBaseEngineState():int getMicroAgentID():MicroAgentID . MicroAgentID getStartTime():long * getStatusMicroAgents():MicroAgentID[ ] getStatusRuleBases():RuleBaseStatus[ ] RuleBaseMonitorEvent getUserData():Object RuleBaseStatus 0..* getRuleBaseStatus():RuleBaseStatus setUserData(:Object) getName():String isValid():boolean getChecksum():long retransmitAlerts(:long[ ]) getAlertIDs():long[] getState():int RuleBaseListMonitorEvent Agent ID getName():String AlertMonitorEvent getDns():String getAlertID():long getHawkDomain():String getRuleBaseEngineState():int hashCode():long ruleBaseStateChanged():boolean equals(:Object):boolean ruleBaseEngineStateChanged():boolean getTimeGenerated():long Agent Version getMajorVersion():int PostAlertEvent getMinorVersion():int getAlertState():int getUpdateVersion():int getAlertText():String getProperties():Properties <> isRetransmittedAlert():boolean AlertState AgentPlatform ALERT_HIGH:int getOsName():String ClearAlertEvent ALERT_MED:int getOsVersion():String getReasonClearedText():String ALERT_LOW:int getOsArch():String match(:PostAlertEvent):boolean NO_ALERT:int

ExceptionEvent getConsoleException():ConsoleException ConsoleException

ErrorExceptionEvent getConsoleError():ConsoleError ConsoleError ConsoleInitializationException WarningExceptionEvent getConsoleWarning():ConsoleWarning ConsoleWarning

TIBCO Hawk Console API Reference Agent Management Classes | 33

Agent Management Classes

TIBCOHawkConsole <> TIBCOHawkConsole(licenseFile:String, *These classes are hawkDomain:String, rvService:String, part of the Hawkeye rvNetwork:String, rvDaemon:String) package. All other <> management classes getAgentManager():AgentManager are members of talon. getAgentMonitor():AgentMonitor AgentMonitor

<> MicroAgentServer AgentManager describe(:MicroAgentID):MicroAgentDescriptor invoke(:MicroAgentID, describe(:MicroAgentID):MicroAgentDescriptor :MethodInvocation):MicroAgentData invoke(:MicroAgentID, :MethodInvocation):MicroAgentData subscribe(:MicroAgentID, :MethodSubscription, subscribe(:MicroAgentID, :MethodSubscription, :SubscriptionHandler, handback:Object):Subscription :SubscriptionHandler, handback:Object):Subscription getMicroAgentIDs(name:String):MicroAgentID[ ] getMicroAgentIDs(name:String):MicroAgentID[ ] getMicroAgentIDs(name:String, max:int):MicroAgentID[ ] groupOp(:MicroAgentID[ ], :MethodInvocation):MicroAgentData[ ] MicroAgentData initialize() initialize(securityImpl:String, securityMode:int) getSource():MicroAgentID shutdown() getData():Object

MethodInvocation <> <> Subscription MethodInvocation(methodName:String, cancel() args:DataElement[ ]) getMethodSubscription() <> :MethodSubscription getMethodName():String getMicroAgentID():MicroAgentID getArguments():DataElement[] getHandback():Object equals(:Object):boolean

MethodSubscription MicroAgentID getName():String <> MicroAgentDescriptor getDisplayName():String MethodSubscription(methodName:String, getInstance():String args:DataElement[ ]) getChecksum():long MethodSubscription(methodName:String, getAgent():Agent args:DataElement[ ], interval:long) <> Illustrated in next isService():boolean getInterval():long diagram. hashCode():int equals(:Object):boolean isAsync():boolean equals(:Object):boolean

MicroAgentException Agent

getName():String <> SubscriptionHandler getDns():String getHawkDomain():String onData(:Subscription, :MicroAgentData) getStartTime():long onError(:Subscription, :MicroAgentException) hashCode():int onErrorCleared(:Subscription) equals(:Object):boolean onTermination(:Subscription, :MicroAgentException)

TIBCO Hawk Console API Reference 34 | Chapter 4 TIBCO Hawk Console API Class Structure

Agent Management Classes (Cont)

MicroAgentDescriptor DataDescriptor

getName():String getName():String getDisplayName():String getType():String getDescription():String getDescription():String getChecksum():long getDefault():Object getMethodDescriptors():MethodDescriptor[ ] getValueChoices():Object[ ] toFormattedString():String getLegalValueChoices:Object[ ] equals(:Object):boolean isOpenData():boolean equals(:Object):boolean

MethodDescriptor IMPACT_ACTION:int CompositeDataDescriptor IMPACT_ACTION_INFO:int IMPACT_INFO: int getElementDescriptors():DataDescriptor[ ] isOpenData():boolean getName():String equals(:Object):boolean getDescription():String getReturnDescriptor():DataDescriptor getArgumentDescriptors():DataDescriptor[ ] getImpact():int getMaxResponseTime():int TabularDataDescriptor isAsync():boolean getColumnNames():String[ ] isOpenMethod():boolean getColumnTypes():String[ ] toFormattedString():String getIndexNames():String[ ] equals(:Object):boolean isOpenData():boolean equals(:Object):boolean

<> CompositeData TabularData OpenData getDataElements():DataElements[ ] getColumnNames():String[ ] types:String[ ] = getValue(:String):Object getColumnTypes():String[ ] "java.lang.String" equals(:Object):boolean getIndexNames():String[] "java.lang.Character" getRow(indexes:DataEkenebt[ ]): "java.lang.Boolean" DataElement[ ] "java.lang.Byte" containsRow(indexes:DataElement[ "java.lang.Short" ]):boolean "java.lang.Integer" getAllDataElements():DataElement[ ] [ ] "java.lang.Long" getAllData():Object[ ] [ ] "java.lang.Float" equals(:Object):boolean "java.lang.Double" DataElement "COM.TIBCO.hawk.talon. CompositeData" getName():String "COM.TIBCO.hawk.talon. getValue():Object TabularData" equals(:Object):boolean

TIBCO Hawk Console API Reference | 35

Chapter 5 Hawkeye Package Interfaces

This chapter describes the COM.TIBCO.hawk.console.hawkeye package interface classes and its methods.

Topics

• Monitoring Alert States with AlertMonitorListener, page 36 • AgentMonitorListener, page 40 • AlertMonitorListener, page 43 • AlertState, page 46 • ErrorExceptionListener, page 47 • ExceptionListener, page 49 • MicroAgentListMonitorListener, page 50 • MonitorListener, page 53 • Method SummaryRuleBaseListMonitorListener, page 56 • RuleBaseMonitorListener, page 59 • WarningExceptionListener, page 60

TIBCO Hawk Console API Reference 36 | Chapter 5 Hawkeye Package Interfaces

Monitoring Alert States with AlertMonitorListener

Changes to the alert states of all agents and their rulebases can be ascertained by monitoring the alerts and clears with the following interface: COM.TIBCO.hawk.console.hawkeye.AlertMonitorListener What is referred to as the agent's alert state is more accurately described as the state of its rulebase engine. The rulebase engine's state is defined as the highest alert state of all the currently loaded and active rulebases. The alert state of a rulebase is the highest alert state of all of its still active (i.e., not cleared) posted alerts.

Only AlertMonitorEvent objects may change the state of a rulebase and thus the rulebase engine of an agent. A PostAlertEvent can potentially increase the alert state of a rulebase. A ClearAlertEvent can potentially decrease the alert state of a rulebase.

Each AlertMonitorEvent is associated with an alert ID and a rulebase. It can be examined upon delivery to determine the following: •The alert ID. • The name of its rulebase. • The states of both its rulebase and the rulebase engine after the event was generated. • Whether it caused a change in either of those states.

All states may be mapped with the constants defined in AlertState.

If the event is a PostAlertEvent, it will also contain an alert state of its own. A PostAlertEvent with alert state of AlertState.NO_ALERT is also called a notification. Rulebases may generate notifications to report on a condition or deliver a message that should not be interpreted as representing a problem.

Example Code The following code fragment illustrates these points: public void onAlertMonitorEvent(AlertMonitorEvent e) { ... // Available to all MonitorEvents AgentInstance myAgentInstance = e.getAgentInstance(); // same as e.(AgentInstance)getSource(); String myAgentName = myAgentInstance.getAgentID().getName(); ... // Available to AlertMonitorEvents long myAlertID = e.getAlertID(); String ruleBaseName = e.getRuleBaseStatus().getName(); int ruleBaseState = e.getRuleBaseStatus().getState();

TIBCO Hawk Console API Reference Monitoring Alert States with AlertMonitorListener | 37

int ruleBaseEngineState = e.getRuleBaseEngineState(); boolean changedRBState = e.ruleBaseStateChanged(); boolean changedEngineState = e.ruleBaseEngineStateChanged(); ... if (e instanceof PostAlertEvent) { int myAlertState = ((PostAlertEvent)e).getAlertState(); boolean isNotification = (myAlertState==AlertState.NO_ALERT) ?true:false; // store it away or report it to the user ... else if (e instanceof ClearAlertEvent) { // look at stored alerts to see which, if any, are now cleared ... } }

Determining Current Alert States and When they Change

All AlertMonitorEvent objects are delivered to onAlertMonitorEvent() in the order in which an agent generates corresponding alerts and clears. They are also delivered in a timely manner soon after the agent generates them. It is therefore possible, within this handler, to determine the current alert states and when they change. A typical use of the AlertMonitorListener interface together with the AgentMonitorListener interface is: 1. Upon discovering an agent is alive in AgentMonitorListener.onAgentAlive(), extract the current states from the delivered AgentInstance object. 2. Thereafter, track all changes to the agent's states using the onAlertMonitorEvent() handler of this interface.

3. When AgentMonitorListener.onAgentExpired() is called for this agent, mark all states and non-cleared alerts to be in a cleared or unknown state. This approach is safe and recommended because:

•All MonitorListener handler methods are invoked serially by the console.

• MonitorEvent objects for a particular AgentInstance are not delivered to any listener before AgentMonitorListener.onAgentAlive() or after AgentMonitorListener.onAgentExpired() is called for that AgentInstance.

TIBCO Hawk Console API Reference 38 | Chapter 5 Hawkeye Package Interfaces

The AlertMonitorListener.onRetransmittedAlert() handler receives retransmitted PostAlertEvent objects whose state accessor methods (ruleBaseStateChanged(), ruleBaseEngineStateChanged(), and getRuleBaseEngineState(), etc.) reflect the state of the agent at some point in the past, that is, the time the corresponding alert was actually generated by the agent. Thus, the state accessor methods of these events cannot be used to determine the current state of the agent. (More on retransmitted alerts below.)

If Your Application Maintains Alerts

If your application maintains PostAlertEvent objects received through this interface, then it may also want to be able to know when the alert conditions they represent have cleared. This can be accomplished by matching ClearAlertEvents to previously received PostAlertEvents. The ClearAlertEvent method match() may be used for this purpose. A single ClearAlertEvent may match multiple previously received PostAlertEvent objects if they represent duplicate alerts. Once a ClearAlertEvent has been received for a particular AgentInstance, no more PostAlertEvent objects will be received with the same alert ID. If the alert condition represented by the PostAlertEvent is cleared but then reoccurs, the reoccurrence will be represented by a separate PostAlertEvent with a different alert ID.

Because events will no longer be delivered for a particular AgentInstance once it is declared expired, it is recommended that applications that use the AlertMonitorListener interface also make use of the AgentMonitorListener interface in order to determine when an agent expires. When an AgentInstance expires, any active (non-cleared) PostAlertEvent object your application maintains for that AgentInstance should be considered to be in an unknown state because, from that point on, you have no way to know the current status of those alert conditions.

It is possible to receive a ClearAlertEvent that doesn't match any previously delivered PostAlertEvent. This would happen if the matching PostAlertEvent was delivered by the agent prior to when your application was started or initialized. These alerts may be retrieved as retransmitted alerts.

Duplicate Alerts

Duplicate alerts are represented by PostAlertEvent objects that have the same alert ID and the same AgentInstance source. It is possible to receive duplicate alerts because a rulebase may be constructed to periodically re-issue an alert while some alert condition exists. As a result, there may be multiple duplicate alerts.

TIBCO Hawk Console API Reference Monitoring Alert States with AlertMonitorListener | 39

Not all attributes of PostAlertEvent objects representing duplicate alerts will be the same, so you must rely on only their alert ID and AgentInstance source in order to identify them as duplicates. For example, the text message in duplicate alerts may differ because of variable substitution which is performed in the rulebase engine. As another example, the value returned by ruleBaseStateChanged() or ruleBaseStateChanged() may be different because the first instance of this duplicate caused the sates to change, not the second.

A duplicate alert may also be a retransmitted alert. Some applications may want to process retransmitted alerts differently that non-retransmitted alerts. All PostAlertEvents may be tested with the isRetransmittedAlert() methods to detect whether or not they are retransmitted alerts.

Retransmitted Alerts

A retransmitted alert is defined as a PostAlertEvent whose isRetransmittedAlert() method returns true. A retransmitted alert may also be a duplicate if other PostAlertEvent objects are received before or after it, bearing the same alert ID and AgentInstance source. This listener may receive a retransmitted alert only after your application has invoked the method AgentInstance.retransmitAlerts(). This method results in a request to the agent to retransmit one or more of its currently active (non-cleared) alerts. It returns immediately and any resulting retransmitted alerts are returned asynchronously to this listener shortly thereafter.

See Also AgentInstance, page 68 AgentMonitorEvent, page 93 AgentMonitorListener, page 40 AlertMonitorEvent, page 96 AlertMonitorListener, page 43 AlertState, page 46 ClearAlertEvent, page 100 ErrorExceptionListener, page 47 MonitorEvent, page 105 MonitorListener, page 53 PostAlertEvent, page 106

TIBCO Hawk Console API Reference 40 | Chapter 5 Hawkeye Package Interfaces

AgentMonitorListener Interface

Package COM.TIBCO.hawk.console.hawkeye

Declaration public interface AgentMonitorListener extends MonitorListener

Purpose Objects implementing AgentMonitorListener are used to receive notifications when agents are discovered to be alive or expired.

Remarks Applications that make use of other MonitorListener interfaces should also consider using an AgentMonitorListener to be notified when a particular AgentInstance has expired. (See MonitorListener for more details.)

Any application that registers an AgentMonitorListener with the TIBHawkConsole should also register an ErrorExceptionListener in order to be notified of critical console errors.

Method Name Description Page Summary AgentMonitorListener.onAgent Receives an event when an agent is 41 Alive() discovered to be alive.

AgentMonitorListener.onAgent Receives an event when an agent is 42 Expired() discovered to have expired.

See Also AgentMonitorEvent, page 93 ErrorExceptionListener, page 47 MonitorListener, page 53

TIBCO Hawk Console API Reference AgentMonitorListener.onAgentAlive() | 41

AgentMonitorListener.onAgentAlive() Method

Declaration public abstract void onAgentAlive( AgentMonitorEvent e)

Purpose Receives an event when an agent is discovered to be alive.

Remarks The agent being reported on is described by the AgentInstance object which is the source of the AgentMonitorEvent object.

Parameters Name Description

e AgentMonitorEvent object generated when the agent was discovered to be alive.

See Also AgentInstance, page 68 AgentMonitorEvent, page 93

TIBCO Hawk Console API Reference 42 | Chapter 5 Hawkeye Package Interfaces

AgentMonitorListener.onAgentExpired() Method

Declaration public abstract void onAgentExpired( AgentMonitorEvent e)

Purpose Receives an event when an agent is discovered to have expired. Expiration can occur if the agent process terminates or if a communications error prevents the console from communicating with the agent.

Remarks The agent being reported on is described by the AgentInstance object which is the source of the AgentMonitorEvent object.

Parameters Name Description

e AgentMonitorEvent object generated when the agent was discovered to have expired.

See Also AgentInstance, page 68 AgentMonitorEvent, page 93

TIBCO Hawk Console API Reference AlertMonitorListener | 43

AlertMonitorListener Interface

Package COM.TIBCO.hawk.console.hawkeye

Declaration public interface AlertMonitorListener extends RuleBaseMonitorListener

Purpose Objects implementing AlertMonitorListener receive all alert related events.

Remarks This interface has two event handler methods, onAlertMonitorEvent() and onRetransmittedAlert() which are both typed to receive object of type AlertMonitorEvent. However, because this is an abstract class, these methods will only receive instances of the concrete subclasses PostAlertEvent (alerts) and ClearAlerEvent (clears).

If an AlertMonitorListener is registered with the console, it will receive these alert and clear events for all agents known to the console. The agents these event pertain to can be determined from their AgentInstance source.

See Monitoring Alert States with AlertMonitorListener on page 36 for details on using this interface. Also see MonitorListener for important information pertaining to all MonitorListener interfaces.

Method Name Description Page Summary AlertMonitorListener.onAlertMonit Receives an event when a retransmitted 44 orEvent() alert or clear is generated by the agent.

AlertMonitorListener.onRetransmit Receives an event when a retransmitted 45 tedAlert() alert is generated by the agent.

See Also AgentInstance, page 68 AgentMonitorEvent, page 93 AlertMonitorEvent, page 96 AlertMonitorListener, page 43 PostAlertEvent, page 106 ClearAlertEvent, page 100 ErrorExceptionListener, page 47 MonitorListener, page 53 Method SummaryRuleBaseListMonitorListener, page 56

TIBCO Hawk Console API Reference 44 | Chapter 5 Hawkeye Package Interfaces

AlertMonitorListener.onAlertMonitorEvent() Method

Declaration public abstract void onAlertMonitorEvent( AlertMonitorEvent e)

Purpose This handler will receive retransmitted PostAlertEvent objects representing alerts and ClearAlertEvent objects representing clears.

Remarks For a particular AgentInstance, events are delivered to this method in the order their corresponding alerts and clears were generated by the agent.

Parameters Name Description

e An AlertMonitorEvent object received when a retransmitted alert or clear is generated by the agent.

See Also AgentInstance, page 68 AgentMonitorEvent, page 93 AlertMonitorEvent, page 96 ClearAlertEvent, page 100 PostAlertEvent, page 106

TIBCO Hawk Console API Reference AlertMonitorListener.onRetransmittedAlert() | 45

AlertMonitorListener.onRetransmittedAlert() Method

Declaration public abstract void onRetransmittedAlert( AlertMonitorEvent e)

Purpose Unlike AlertMonitorListener.onAlertMonitorEvent(), this handler will only receive retransmitted PostAlertEvent objects (and not ClearAlertEvent objects).

Parameters Name Description

e An AlertMonitorEvent object received when a retransmitted alert is generated by the agent.

See Also AgentInstance, page 68 AgentMonitorEvent, page 93 AlertMonitorEvent, page 96 PostAlertEvent, page 106

TIBCO Hawk Console API Reference 46 | Chapter 5 Hawkeye Package Interfaces

AlertState Interface

Package COM.TIBCO.hawk.console.hawkeye

Declaration public interface AlertState

Purpose The data member integer constants specify the level of alert. For more information, see Alert Monitoring on page 16 and Monitoring Alert States with AlertMonitorListener on page 36.

Constants Name Description Summary NO_ALERT A notification level alert.

ALERT_LOW A low alert.

ALERT_MEDIUM A medium alert.

ALERT_HIGH A high alert.

TIBCO Hawk Console API Reference ErrorExceptionListener | 47

ErrorExceptionListener Interface

Package COM.TIBCO.hawk.console.hawkeye

Declaration public interface ErrorExceptionListener extends ExceptionListener

Purpose Receives a notification when the TIBHawkConsole is no longer able to continue generating MonitorEvents due to some critical error.

Remarks Any application that receives MonitorEvents must also register to receive ErrorExceptionEvents with this interface if it wishes to know when it can no longer be serviced.

If an ErrorExceptionEvent is delivered, the recommended action is to notify the user of the exception and exit. An example of such an event is when the agent doesn’t receive the expected initial values.

Method Name Description Page Summary ErrorExceptionListener.onError Called when a critical console error occurs 48 ExceptionEvent()

See Also ErrorExceptionEvent, page 102 ExceptionListener, page 49 MonitorEvent, page 105 TIBHawkConsole, page 113

TIBCO Hawk Console API Reference 48 | Chapter 5 Hawkeye Package Interfaces

ErrorExceptionListener.onErrorExceptionEvent() Method

Declaration public abstract void onErrorExceptionEvent( ErrorExceptionEvent e)

Purpose Called when a critical console error occurs.

Parameters Name Description

e The ErrorException identifying the critical console error.

See Also ErrorExceptionEvent, page 102

TIBCO Hawk Console API Reference ExceptionListener | 49

ExceptionListener Interface

Package COM.TIBCO.hawk.console.hawkeye

Declaration public interface ExceptionListener extends EventListener

Purpose A marker interface extended by the exception-related TIBHawkConsole event listeners.

See Also ErrorExceptionListener, page 47 WarningExceptionListener, page 60

TIBCO Hawk Console API Reference 50 | Chapter 5 Hawkeye Package Interfaces

MicroAgentListMonitorListener Interface

Package COM.TIBCO.hawk.console.hawkeye

Declaration public interface MicroAgentListMonitorListener extends MonitorListener

Purpose Receives notifications of microagent add and remove events.

Remarks Applications using a MicroAgentMonitorListListener object could optionally use an AgentMonitorListener to detect expiration of a particular AgentInstance. This is because an expired AgentInstance does not generate further MonitorEvents, including the MicroAgentListMonitorEvents.

Method Name Description Page Summary MicroAgentListMonitorListener Detects an added microagent. 51 .onMicroAgentAdded()

MicroAgentListMonitorListener Detects a deleted microagent. 52 .onMicroAgentRemoved()

See Also AgentMonitorListener, page 40 ErrorExceptionListener, page 47 MicroAgentListMonitorEvent, page 104 MonitorEvent, page 105

TIBCO Hawk Console API Reference MicroAgentListMonitorListener.onMicroAgentAdded() | 51

MicroAgentListMonitorListener.onMicroAgentAdded() Method

Declaration public abstract void onMicroAgentAdded( MicroAgentListMonitorEvent e)

Purpose Detects an added microagent.

Parameters Name Description

e A MicroAgentListMonitorEvent object, generated because the agent's list of currently loaded microagents changed.

See Also MicroAgentListMonitorEvent, page 104

TIBCO Hawk Console API Reference 52 | Chapter 5 Hawkeye Package Interfaces

MicroAgentListMonitorListener.onMicroAgentRemoved() Method

Declaration public abstract void onMicroAgentRemoved( MicroAgentListMonitorEvent e)

Purpose Detects a deleted microagent.

Parameters Name Description

e A MicroAgentListMonitorEvent object, generated because the agent's list of currently loaded microagents changed.

See Also MicroAgentListMonitorEvent, page 104

TIBCO Hawk Console API Reference MonitorListener | 53

MonitorListener Interface

Package COM.TIBCO.hawk.console.hawkeye

Declaration public interface MonitorListener extends EventListener

Purpose A marker interface extended by all monitoring-related TIBHawkConsole event listeners. The sub-interfaces of MonitorListener include:

• AgentMonitorListener

• MicroAgentMonitorListener

• RuleBaseMonitorListener

— RuleBaseListMonitorListener

— AlertMonitorListener

These sub-interfaces register delivery of MonitorEvent objects with the TIBHawkConsole. The console delivers all events to all MonitorListener objects in a single thread. All MonitorEvent objects pertain to individual agents and track agent status. The event source is always the AgentInstance object identifying the agent that was the logical origin of the event.

A registered listener for a particular type of MonitorEvent receives notifications for all monitored agents generating that event. For example, registering an AgentMonitorEventListener with the console allows it to receive AgentMonitorEvents for all agents known to the console, thus allowing it to track the alive or expired status of every agent.

AgentInstance, AgentID, and MonitorListener

All MonitorEvents delivered to MonitorListener interfaces contain an AgentInstance object as their source. When the console discovers an agent, it creates a unique AgentInstance object and delivers it to AgentMonitorListener.onAgentAlive() in an event. It then begins delivering monitor events for that AgentInstance to the other registered MonitorListener objects. If the console loses communication with that agent, it delivers that same AgentInstance object to AgentMonitorListener.onAgentExpired() in an event.

TIBCO Hawk Console API Reference 54 | Chapter 5 Hawkeye Package Interfaces

No MonitorEvents are delivered from a particular AgentInstance object before the console calls AgentMonitorListener.onAgentAlive() or after it calls AgentMonitorListener.onAgentExpired() for that same AgentInstance object. Thus, AgentInstance objects represent a communications session with a particular agent. The life span of this session begins with a call to AgentMonitorListener.onAgentAlive() and ends with a call to AgentMonitorListener.onAgentExpired(). When the console loses and then reestablishes communication with an agent (such as when an agent process is restarted or when a temporary network disconnect occurs), a new AgentInstance object is generated to represent the new session.

AgentInstance objects contain an AgentID object. AgentID objects can be used to associate MonitorEvents with real agent processes across the communication sessions represented by AgentInstance objects. If an agent is restarted, the AgentID in the new AgentInstance object is equal that in the old AgentInstance.

AgentID objects identify real agent processes through the combination of agent name, agent DNS name, and TIBCO Hawk domain. The TIBCO Hawk system requires that all running agents have a unique combination of these three values. The system administrator must ensure that every real agent running in the network has a unique combination of these three values. If the console detects that more than one real agent has the same AgentID, it produces a WarningExceptionEvent (See WarningExceptionListener).

Events are no longer delivered for a particular AgentInstance once it is declared expired. Therefore, applications that use any of the MonitorListener sub-interfaces should also use the AgentMonitorListener interface to monitor for agent expiration. For example, if you use an AlertMonitorListener to track agent alerts, it is useful to learn when you no longer receive alerts for a particular AgentInstance.

It is strongly recommended that applications using MonitorEventListers also use the ErrorExceptionListener interface to be notified of any critical console errors. If a critical console error occurs, the console cannot deliver further MonitorEvents.

See Also AgentID, page 64 AgentInstance, page 68 AgentMonitorEvent, page 93 AgentMonitorListener, page 40 AlertMonitorListener, page 43 ErrorExceptionListener, page 47 MonitorEvent, page 105 Method SummaryRuleBaseListMonitorListener, page 56

TIBCO Hawk Console API Reference MonitorListener | 55

RuleBaseMonitorListener, page 59 AgentPlatform, page 94 WarningExceptionEvent, page 119 WarningExceptionListener, page 60

TIBCO Hawk Console API Reference 56 | Chapter 5 Hawkeye Package Interfaces

Method SummaryRuleBaseListMonitorListener Interface

Package COM.TIBCO.hawk.console.hawkeye

Declaration public interface RuleBaseListMonitorListener extends RuleBaseMonitorListener

Purpose Receives notifications of rulebase add or remove events.

Remarks An application that make use of a RuleBaseListMonitorListener object should also consider using an AgentMonitorListener so that it can learn when a particular AgentInstance has expired. This is relevant because an expired AgentInstance will never generate any more MonitorEvents, including RuleBaseListMonitorEvents.

Method Name Description Page Summary RuleBaseListMonitorListener.on Detect RuleBaseAdded. 57 RuleBaseAdded()

RuleBaseListMonitorListener.on Detect RuleBaseRemoved. 58 RuleBaseRemoved()

See Also RuleBaseMonitorListener, page 59

TIBCO Hawk Console API Reference RuleBaseListMonitorListener.onRuleBaseAdded() | 57

RuleBaseListMonitorListener.onRuleBaseAdded() Method

Declaration public abstract void onRuleBaseAdded( RuleBaseListMonitorEvent e)

Purpose Detects that a rulebase was added.

Parameters Name Description

e A RuleBaseListMonitorEvent object, generated because the agent's list of currently loaded rulebases changed.

See Also RuleBaseListMonitorEvent, page 109

TIBCO Hawk Console API Reference 58 | Chapter 5 Hawkeye Package Interfaces

RuleBaseListMonitorListener.onRuleBaseRemoved() Method

Declaration public abstract void onRuleBaseRemoved( RuleBaseListMonitorEvent e)

Purpose Detects that a rulebase was removed.

Parameters Name Description

e A RuleBaseListMonitorEvent object, generated because the agent's list of currently loaded rulebases changed.

See Also RuleBaseListMonitorEvent, page 109

TIBCO Hawk Console API Reference RuleBaseMonitorListener | 59

RuleBaseMonitorListener Interface

Package COM.TIBCO.hawk.console.hawkeye

Declaration public interface RuleBaseMonitorListener extends MonitorListener

Purpose This interface is the parent of all listener interfaces associated with rulebase- related events.

See Also AlertMonitorListener, page 43 MonitorListener, page 53 Method SummaryRuleBaseListMonitorListener, page 56

TIBCO Hawk Console API Reference 60 | Chapter 5 Hawkeye Package Interfaces

WarningExceptionListener Interface

Package COM.TIBCO.hawk.console.hawkeye

Declaration public interface WarningExceptionListener extends ExceptionListener

Purpose Receives a notification when TIBHawkConsole has detected a non-critical error (warning) condition in its processing of MonitorEvents, for example detection of a duplicate agent.

Remarks If a WarningExceptionEvent is delivered, the recommended action is to warn the user that this event has occurred. If the application has a GUI component, an appropriate action might be opening a warning notice window.

Method Name Description Page Summary WarningExceptionListener. Called when the console generates a 61 onWarningExceptionEvent() warning

See Also ExceptionListener, page 49

TIBCO Hawk Console API Reference WarningExceptionListener.onWarningExceptionEvent() | 61

WarningExceptionListener.onWarningExceptionEvent() Method

Declaration public abstract void onWarningExceptionEvent( WarningExceptionEvent e)

Purpose Called when TIBHawkConsole has detected a non-critical error (warning) condition in its processing of MonitorEvents.

Parameters Name Description

e A WarningExceptionEvent object, generated when a non-critical error condition is detected.

See Also MonitorEvent, page 105 WarningExceptionEvent, page 119 TIBHawkConsole, page 113

TIBCO Hawk Console API Reference 62 | Chapter 5 Hawkeye Package Interfaces

TIBCO Hawk Console API Reference | 63

Chapter 6 Hawkeye Package Classes

This chapter describes the COM.TIBCO.hawk.console.hawkeye package classes and its methods.

Topics

• AgentID, page 64 • AgentInstance, page 68 • AgentMonitor, page 86 • AgentMonitorEvent, page 93 • AgentPlatform, page 94 • AgentVersion, page 95 • AlertMonitorEvent, page 96 • ClearAlertEvent, page 100 • ErrorExceptionEvent, page 102 • ExceptionEvent, page 103 • MicroAgentListMonitorEvent, page 104 • MonitorEvent, page 105 • PostAlertEvent, page 106 • RuleBaseListMonitorEvent, page 109 • RuleBaseMonitorEvent, page 110 • RuleBaseStatus, page 111 • TIBHawkConsole, page 113 • WarningExceptionEvent, page 119

TIBCO Hawk Console API Reference 64 | Chapter 6 Hawkeye Package Classes

AgentID Class

Package COM.TIBCO.hawk.console.hawkeye

Declaration public class AgentID extends Object

Purpose AgentID objects identify real agent processes through the combination of agent name, agent dns name, and hawk domain. The TIBCO Hawk system requires that all running agents have a unique combination of these three values.

Method Name Description Page Summary AgentID.getDns() Returns the DNS name of the agent (String). 65 The DNS name is used to distinguish between two agents that have the same name attribute.

AgentID.getHawkDomain() Returns the TIBCO Hawk domain name of 66 this agent (String).

AgentID.getName() Returns the name of this agent (String). 67

See Also AgentInstance, page 68 MonitorListener, page 53

TIBCO Hawk Console API Reference AgentID.getDns() | 65

AgentID.getDns() Method

Declaration public String getDNS()

Purpose Returns the dns name of the agent. The dns name is used to distinguish between two agents that have the same name attribute.

TIBCO Hawk Console API Reference 66 | Chapter 6 Hawkeye Package Classes

AgentID.getHawkDomain() Method

Declaration public String getHawkDomain()

Purpose Returns the hawk domain of the agent.

TIBCO Hawk Console API Reference AgentID.getName() | 67

AgentID.getName() Method

Declaration public String getName()

Purpose Returns the name of the agent

TIBCO Hawk Console API Reference 68 | Chapter 6 Hawkeye Package Classes

AgentInstance Class

Package COM.TIBCO.hawk.console.hawkeye

Declaration public class AgentInstance extends Object

Purpose AgentInstance objects represent agents. When the AgentMonitor discovers an agent, a new AgentInstance object is instantiated to represent it. When the AgentMonitor detects that an agent has expired, the corresponding AgentInstance object is marked as invalid.

Remarks AgentInstance objects are used as the source for all agent specific monitoring events. For more information on use of this class, see The AgentInstance Class on page 12.

Method Name Description Page Summary AgentInstance.get...() Accessors Returns information relating to this 69 agent. Methods are: getAgentID() getAgentPlatform() getAgentVersion() getCluster() getIPAddress() getRuleBaseEngineState() getStartTime() getStatusMicroAgents() getStatusRuleBases() getUserData()

AgentInstance.isValid() Returns true if this AgentInstance is 71 still valid, false otherwise.

AgentInstance.retransmitAlerts() Requests that the agent retransmit the 72 active alerts indicated by AlertID.

AgentInstance.setUserData() Sets the user data (Object). 74

See Also AgentMonitor, page 86 MonitorListener, page 53

TIBCO Hawk Console API Reference AgentInstance.get...() Accessors | 69

AgentInstance.get...() Accessors Accessors

Declaration public AgentID getAgentID() public AgentPlatform getAgentPlatform() public AgentVersion getAgentVersion() public String getCluster() public String getIPAddress() public int getRuleBaseEngineState() public long getStartTime() public MicroAgentID[] getStatusMicroAgents() public RuleBaseStatus[] getStatusRuleBases() public Object getUserData()

Purpose Returns information about this agent

Method Name Description Summary getAgentID() Returns the AgentID of this agent.

getAgentPlatform() Returns the agent platform.

getAgentVersion() Returns the agent version.

getCluster() Returns the cluster parameter used to initialize the agent.

getIPAddress() Returns the IP address string: %d.%d.%d.%d

getRuleBaseEngineState() Returns the current state of the agent's rulebase engine. The value can be mapped to a symbolic value using the AlertState interface.

getStartTime() Returns the time the agent was initialized, from the perspective of the system clock on the host the agent is running on. This value is the number of milliseconds since January 1, 1970, 00:00:00 GMT.

getStatusMicroAgents() Returns a list representing the currently loaded microagents.

getStatusRuleBases() Returns a list representing the currently loaded and active rulebases.

getUserData() Returns the user data.

See Also AgentInstance, page 68 AgentID, page 64 AgentPlatform, page 94 AgentVersion, page 95

TIBCO Hawk Console API Reference 70 | Chapter 6 Hawkeye Package Classes

AlertState, page 46 MicroAgentID, page 182 RuleBaseStatus, page 111

TIBCO Hawk Console API Reference AgentInstance.isValid() | 71

AgentInstance.isValid() Method

Declaration public boolean isValid()

Purpose Returns true if this AgentInstance is still valid, false otherwise.

Remarks An AgentInstance will become invalid when the agent it represents is declared as expired.

See Also AgentMonitorListener, page 40

TIBCO Hawk Console API Reference 72 | Chapter 6 Hawkeye Package Classes

AgentInstance.retransmitAlerts() Method

Declaration public void retransmitAlerts( long alertIDs[])

Purpose Requests that the agent retransmit the active alerts indicated by alertIDs. A null argument requests all currently active alerts. This method does not block. The requested alerts are delivered asynchronously to the onRetransmittedAlert() handler method of the AgentMonitorListener registered with the console in the form of PostAlertEvent objects whose isRetransmitted() method returns true.

Remarks An active alert is defined as one that has not yet been cleared. Invoke getAlertIDs() on the RuleBaseStatus elements of the array returned by getStatusRuleBases() to learn what alerts are currently active on each rulebase. If you request a retransmission of a cleared alert, it will not be returned.

It is possible for you make a request for an alert you believe to be active but which is cleared before your request reaches the agent. The agent treats such requests as a request for a non-active alert and as such they are not serviced. Also, the agent does not maintain all copies of duplicate alerts. It maintains only the most recently delivered copy. (See AgentMonitorListener on page 40 for more details and a description of duplicate alerts.)

This facility allows applications using the TIBHawkConsole to retrieve alerts that agents might have delivered prior to console initialization. Typically, agents are already running when a console application starts. These agents could have already issued alerts which are still outstanding. When an agent is discovered by the AgentMonitorListener.onAgentAlive() method, the AgentInstance source of that event can be examined to learn the alertIDs of all outstanding alerts the agent had at the time of discovery. It can then request a retransmission of one or more of those alerts using their AlertID values.

On networks with a large number of agents, it is NOT advisable to automatically request retransmissions for all outstanding alerts from all agents, on discovery. Doing so can result in an unacceptably large number of simultaneous network messages, as all agents attempt to service your requests.

The best strategy is to retrieve these alerts on an as-needed basis. If your application needs all currently-outstanding alerts at start time, it should throttle its requests. In determining the throttle rate, you should consider the average number of alerts that can be outstanding on the entire network at the times when your application could be started. This is an empirical measure that might best be treated as a configuration option with a conservative default value.

TIBCO Hawk Console API Reference AgentInstance.retransmitAlerts() | 73

See Also AgentMonitorListener, page 40 AlertMonitorListener, page 43 PostAlertEvent, page 106

TIBCO Hawk Console API Reference 74 | Chapter 6 Hawkeye Package Classes

AgentInstance.setUserData() Method

Declaration public void setUserData(Object userData)

Purpose Sets the user data.

Parameters Name Description userData The object used to set the user data.

TIBCO Hawk Console API Reference AgentManager | 75

AgentManager Class

Package COM.TIBCO.hawk.console.hawkeye

Declaration public class AgentManager extends Object implements MicroAgentServer

Purpose The AgentManager is used to monitor TIBCO Hawk agent events. The AgentManager itself is both thread-safe and thread-aware.

Remarks The correct general procedure for using the AgentManager class is:

1. Call initialize() to initialize the AgentManager. 2. Perform any desired management activities.

3. Call shutdown() when done.

Method Name Description Page Summary AgentManager.describe() Retrieves a descriptor for a 76 microagent.

AgentManager.getMicroAgentIDs() Queries all agents to learn the ID 77 of all microagents matching the supplied name.

AgentManager.getMicroAgentIDs() Queries specific agents to learn 78 the IDs of microagents matching the supplied name.

AgentManager.groupOp() Performs a group operation. 79

AgentManager.invoke() Performs a method invocation on a 81 microagent.

AgentManager.initialize() Initializes an AgentManager. 80

AgentManager.shutdown() Used to gracefully shutdown the 83 AgentManager.

AgentManager.subscribe() Registers a subscription with a 84 microagent.

See Also MicroAgentServer, page 128

TIBCO Hawk Console API Reference 76 | Chapter 6 Hawkeye Package Classes

AgentManager.describe() Method

Declaration public MicroAgentDescriptor describe( MicroAgentID id) throws MicroAgentException

Purpose Returns a descriptor for a microagent or null if the descriptor is not present. The descriptor describes the microagent and all of its methods.

Remarks This method is required to properly construct and perform method invocations and subscription against a microagent.

Throws IllegalArgumentException if the argument is null or an empty string.

Throws MicroAgentException if a problem occurred servicing this request.

Parameters Name Description id The microagent ID of the microagent to describe.

See Also MicroAgentID, page 182 MicroAgentException, page 196

TIBCO Hawk Console API Reference AgentManager.getMicroAgentIDs() | 77

AgentManager.getMicroAgentIDs() Method

Declaration public MicroAgentID[] getMicroAgentIDs( String microAgentName) throws MicroAgentException

public MicroAgentID[] getMicroAgentIDs( String microAgentName, int minNum) throws MicroAgentException

Purpose Queries all agents to learn the ID of all microagents matching the supplied name.

Returns a list of MicroAgentID objects identifying all microagents matching the supplied name that were discovered to be running on all agents.

Remarks The second form is faster than the first if the number of actual matching microagents on the network is greater than or equal to the supplied minNum value.

If your application is also using the AgentMonitor to track agents and their microagents then it is more efficient to use the data supplied by the AgentMonitor rather than this method.

Throws MicroAgentException if a problem occurred servicing this request.

Parameters Name Description microAgentName The microagent name.

minNum The minimum number of agents you want to discover.

See Also AgentMonitor, page 86 MicroAgentID, page 182 MicroAgentException, page 196

TIBCO Hawk Console API Reference 78 | Chapter 6 Hawkeye Package Classes

AgentManager.getMicroAgentIDs() Constructor

Declaration public MicroAgentID[] getMicroAgentIDs(String agentName, String agentDns, String hawkDomain, String microAgentName, int minNum)

Purpose Queries specific agents to learn the IDs of microagents matching the supplied name. The first three parameters (agentName, agentDns, and hawkDomain) identify the target agent(s). Any or all of these can be null to indicate a wildcard. Setting all three to null has the same effect as calling AgentManager.getMicroAgentIDs(). You can programmatically filter out unwanted replies by examining which agent they came from and ignoring replies which are not from the targeted agent(s).

Parameters Name Description agentName The name of the targeted agent. Use null or empty-string to match any agent name.

agentDns The dns value of the targeted agent. Use null or empty-string to match any dns value.

hawkDomain The hawkDomain of the targeted agent. NOTE: Currently, each instance of AgentManager is bound to a single hawk domain. Therefore, using any value other than that specific domain, null, or empty-string will return without discovering any agents.

microAgentName The microagent name.

minNum The minimum number of microagents you want to discover. Use zero to discover all available microagents (subject to a timeout interval).

Throws MicroAgentException if an error occurs while satisfying the request.

TIBCO Hawk Console API Reference AgentManager.groupOp() | 79

AgentManager.groupOp() Method

Declaration public MicroAgentData[] groupOp( MicroAgentID targets[], MethodInvocation mi) throws MicroAgentException

Purpose Performs a group operation. Invokes the supplied method invocation on all target microagents.

Remarks Throws MicroAgentException if a problem occurred servicing this request.

Parameters Name Description

targets The list of MicroAgentID objects identifying what microagents are to be invoked.

mi The MethodInvocation object identifying the method to be invoked and its arguments. Cannot be null.

See Also MicroAgentID, page 182 MicroAgentData, page 176 MicroAgentException, page 196

TIBCO Hawk Console API Reference 80 | Chapter 6 Hawkeye Package Classes

AgentManager.initialize() Method

Declaration public void initialize() throws ConsoleInitializationException

public void initialize( String securityImpl, int securityMode) throws ConsoleInitializationException

Purpose The first form initializes an AgentManager. The second form initializes a secure AgentManager.

Remarks The securityMode parameter signals the context of the invoker. Possible contexts are:

• HsConsoleInterface.WINDOW: indicates an interactive windowing environment. It is possible to perform interactive activities from within this context.

• HsConsoleInterface.CONSOLE: indicates an interactive console session. It is also possible to perform interactive command-line activities from within this context.

• HsConsoleInterface.DAEMON: indicates a non-interactive batch or background process. It is not possible to perform interactive activites from within this context. See the TIBCO Hawk Programmer’s Guide for information on security policy implementation and security context.

Throws ConsoleInitializationException if an initialization error occurred

Parameters Name Description securityImpl The name of the class implementing the security policy.

securityMode The context of the invoker.

See Also ConsoleInitializationException, page 124

TIBCO Hawk Console API Reference AgentManager.invoke() | 81

AgentManager.invoke() Method

Declaration public MicroAgentData invoke( MicroAgentID id, MethodInvocation mi) throws MicroAgentException

Purpose Performs a method invocation on a microagent.

Remarks The results of the invocation are delivered in the data field of the MicroAgentData return. Two general types of errors can occur with method invocations: • Errors during the delivery of a method invocation to, or the returning the results from, a microagent. This condition will cause this method to throw a MicroAgentException. • Errors during the invocation of the method on the microagent itself. This condition will cause this method to deliver a MicroAgentException in the data field of the MicroAgentData return. Thus, a successful method invocation is one that doesn't throw an exception and doesn’t deliver a MicroAgentException in the data field of its MicroAgentData return.

If the method invocation is successful, the data field of its MicroAgentData return will contain the method's return value or null if the method doesn't return a value. You should not invoke to methods that are non-open (proprietary) unless you have their supporting API and documentation, as this can create unpredictable results. Whether or not a method is open is defined by its MethodDescriptor.

Throws IllegalArgumentException if the parameter conditions are violated.

Throws MicroAgentException if an error occurs during the delivery of a method invocation to, or the results back from, a microagent.

Parameters Name Description id The microagent ID of the target microagent.

mi The MethodInvocation object identifying the method to be invoked and its arguments. Cannot be null.

See Also MethodInvocation, page 169 MicroAgentData, page 176

TIBCO Hawk Console API Reference 82 | Chapter 6 Hawkeye Package Classes

MicroAgentException, page 196 MicroAgentID, page 182

TIBCO Hawk Console API Reference AgentManager.shutdown() | 83

AgentManager.shutdown() Method

Declaration public void shutdown()

Purpose Used to gracefully shut down the AgentManager.

Remarks Calling this method more than once has no effect.

TIBCO Hawk Console API Reference 84 | Chapter 6 Hawkeye Package Classes

AgentManager.subscribe() Method

Declaration public Subscription subscribe( MicroAgentID id, MethodSubscription msub, SubscriptionHandler handler, Object handBack) throws MicroAgentException

Purpose Registers a subscription with a microagent. Subscriptions are made against microagent methods. Returns a subscription object that can be used to cancel the subscription and to examine how the subscription was created. This object is also passed to the SubscriptionHandler methods as the subscription is being serviced.

Remarks Subscriptions are made against microagent methods. Registering a subscription is analogous to registering for events, where the a microagent's method is the event source. The subscribed-to data is delivered asynchronously to the supplied SubscriptionHandler. Two general types of errors can occur during method invocations: • Those that occur during the registration of the subscription. This condition will cause this method to throw a MicroAgentException. • Those that occur during the servicing of the subscription These errors are delivered to the SubscriptionHandler.

Throws IllegalArgumentException if the parameter conditions are violated.

Throws MicroAgentException If an error occurs during the registration of the subscription.

Parameters Name Description id The microagent ID of the target microagent.

msub Identifies what is being subscribed to.

handler The object that handles subscription results.

handBack This Object parameter is accessible in the resulting Subscription object which is delivered to the handler along with subscription results.

See Also MethodSubscription, page 171

TIBCO Hawk Console API Reference AgentManager.subscribe() | 85

MicroAgentID, page 182 MicroAgentException, page 196 SubscriptionHandler, page 137

TIBCO Hawk Console API Reference 86 | Chapter 6 Hawkeye Package Classes

AgentMonitor Class

Package COM.TIBCO.hawk.console.hawkeye

Declaration class AgentMonitor extends Object

Purpose The AgentMonitor monitors TIBCO Hawk agent events.

Remarks The AgentMonitor delivers two general types of asynchronous events to registered listeners.

•Subclasses of MonitorEvent are delivered to the subclasses of MonitorListener. They pertain to individual agents and are used to track agent status.

•Subclasses of ExceptionEvent are delivered to subclasses of ExceptionListener. They report on problems the AgentMonitor encounters during its monitoring activities.

AgentMonitor supports the adding of a single listener object with addXXXListener() methods for the following listener classes:

• AgentMonitorListener: for notification of agent discovery and expiration.

• MicroAgentListMonitorListener: for notification of microagent add or remove events.

• RuleBaseListMonitorListener: for notification of rulebase addor remove events.

• AlertMonitorListener: to receive all alert related events.

• ErrorExceptionListener: for notification of critical error events relating to the AgentMonitor's ability to perform monitoring.

• WarningExceptionListener:for notification of warning events relating to the AgentMonitor's ability to perform monitoring.

The listeners are delivered events from the Java EventObject hawkeye package classes MonitorEvent and its subclasses, and ExceptionEvent and its subclasses.

The AgentMonitor itself is both thread-safe and thread-aware.

All MonitorEvents are delivered to the listeners in a single message dispatch thread, which receives messages from agents and dispatches them to the appropriate event handler methods. The event handler methods of all MonitorListener interfaces are executed serially.

TIBCO Hawk Console API Reference AgentMonitor | 87

Because the event handler methods run serially, you must ensure that they complete their task and return quickly, without extended computations and without blocking. If a method must compute at length, it should spawn a separate thread to complete its task.

The documentation provided with the MonitorListener interface provides additional important information regarding the handling of all MonitorEvent types.

Using the The correct general procedure for using the AgentMonitor class is: AgentMonitor 1. Add any desired event listeners to receive notifications. Class 2. Call initialize() to start the AgentMonitor's monitoring activities.

3. Call shutdown() when done.

Method Name Description Page Summary AgentMonitor.add...() Methods used to add various listener objects to 89 Methods the console: addAgentMonitorListener() addAlertMonitorListener() addErrorExceptionListener() addMicroAgentListMonitorListener() addRuleBaseListMonitorListener() addWarningExceptionrListener()

AgentMonitor.initialize() Initializes the AgentMonitor. 90

AgentMonitor.remove...() Methods used to remove various listener objects 92 Methods from the console: removeAgentMonitorListener() removeAlertMonitorListener() removeErrorExceptionListener() removeMicroAgentListMonitorListener () removeRuleBaseListMonitorListener() removeWarningExceptionrListener()

AgentMonitor.shutdown() Used to gracefully shut down the 92 AgentMonitor.

See Also AgentMonitorListener, page 40 AlertMonitorListener, page 43

TIBCO Hawk Console API Reference 88 | Chapter 6 Hawkeye Package Classes

ErrorExceptionListener, page 47 ExceptionEvent, page 103 ExceptionListener, page 49 MicroAgentListMonitorListener, page 50 MonitorEvent, page 105 MonitorListener, page 53 Method SummaryRuleBaseListMonitorListener, page 56 WarningExceptionListener, page 60

TIBCO Hawk Console API Reference AgentMonitor.add...() Methods | 89

AgentMonitor.add...() Methods Method

Declaration public void addAgentMonitorListener( AgentMonitorListener l) throws TooManyListenersException

Purpose Adds an object of the specified type to the console.

Remarks For each method, the form of the declaration is like that shown, where parameter l is an object of the type to be added.

Throws IllegalStateException if this method was called after initialize() or after shutdown().

Throws TooManyListenersException if a listener is already registered.

Method Name Description Summary addAgentMonitorListener() Adds an AgentMonitorListener.

addAlertMonitorListener() Adds an AlertMonitorListener.

addErrorExceptionListener() Adds an ErrorExceptionListener.

addMicroAgentListMonitorListener() Adds a MicroAgentListMonitorListener.

addRuleBaseListMonitorListener() Adds a RuleBaseListMonitorListener.

addWarningExceptionrListener() Adds a WarningExceptionListener.

See Also AgentMonitorListener, page 40 AlertMonitorListener, page 43 ErrorExceptionListener, page 47 MicroAgentListMonitorListener, page 50 Method SummaryRuleBaseListMonitorListener, page 56 WarningExceptionListener, page 60

TIBCO Hawk Console API Reference 90 | Chapter 6 Hawkeye Package Classes

AgentMonitor.initialize() Method

Declaration public void initialize() throws ConsoleInitializationException

Purpose Initializes the AgentMonitor. Cannot be called more than once per AgentMonitor instance.

Remarks Throws IllegalStateException if called more than once.

Throws ConsoleInitializationException if an initialization error occurred.

See Also ConsoleInitializationException, page 124

TIBCO Hawk Console API Reference AgentMonitor.remove...() Methods | 91

AgentMonitor.remove...() Methods Method

Declaration public void removeAgentMonitorListener( AgentMonitorListener l)

Purpose Removes an object of the specified type from the console.

Remarks For each method, the form of the declaration is like that shown, where parameter l is an object of the type to be removed.

Throws IllegalStateException if called after initialize()

Method Name Description Summary removeAgentMonitorListener() Removes an AgentMonitorListener.

removeAlertMonitorListener() Removes an AlertMonitorListener.

removeErrorExceptionListener() Removes an ErrorExceptionListener.

removeMicroAgentListMonitorListener() Removes a MicroAgentListMonitorListener.

removeRuleBaseListMonitorListener() Removes a RuleBaseListMonitorListener.

removeWarningExceptionrListener() Removes a WarningExceptionListener.

See Also AgentMonitor.initialize(), page 90 AgentMonitorListener, page 40 AlertMonitorListener, page 43 ErrorExceptionListener, page 47 MicroAgentListMonitorListener, page 50 Method SummaryRuleBaseListMonitorListener, page 56 WarningExceptionListener, page 60

TIBCO Hawk Console API Reference 92 | Chapter 6 Hawkeye Package Classes

AgentMonitor.shutdown() Method

Declaration public void shutdown()

Purpose Used to gracefully shutdown the AgentMonitor.

Remarks Calling this method more than once has no effect.

Throws IllegalStateException if called after initialize().

See Also AgentMonitor.initialize(), page 90

TIBCO Hawk Console API Reference AgentMonitorEvent | 93

AgentMonitorEvent Class

Package COM.TIBCO.hawk.console.hawkeye

Declaration public class AgentMonitorEvent extends MonitorEvent

Purpose AgentMonitorEvent objects are generated when agents are discovered to be alive or expired. The source of the event is the AgentInstance object that identifies the particular agent from which the event logically originated.

See Also AgentMonitorListener, page 40 AgentInstance, page 68 MonitorEvent, page 105

TIBCO Hawk Console API Reference 94 | Chapter 6 Hawkeye Package Classes

AgentPlatform Class

Package COM.TIBCO.hawk.console.hawkeye

Declaration public class AgentPlatform extends Object

Purpose Returns operating system information for an agent’s platform.

Method Name Description Summary AgentPlatform.getOsArch() Returns the operating system architecture (String).

AgentPlatform.getOsName() Returns the operating system name (String).

AgentPlatform.getOsVersion() Returns the operating system version (String).

TIBCO Hawk Console API Reference AgentVersion | 95

AgentVersion Class

Package COM.TIBCO.hawk.console.hawkeye

Declaration public class AgentVersion extends Object

Purpose Gets version information.

Method Name Description Summary AgentVersion.getMajorVersion() Returns the major version number of the agent (int).

AgentVersion.getMinorVersion() Returns the minor version number of the agent (int).

AgentVersion.getUpdateVersion() Returns the update version number of the agent (int).

TIBCO Hawk Console API Reference 96 | Chapter 6 Hawkeye Package Classes

AlertMonitorEvent Class

Package COM.TIBCO.hawk.console.hawkeye

Declaration public abstract class AlertMonitorEvent extends RuleBaseMonitorEvent

Purpose This is the root class for all alert related events. The sub-classes of this class are:

• PostAlertEvent - generated when alerts are posted.

• ClearAlertEvent - generated when alerts are cleared. Alerts are posted and cleared by rulebases that are loaded in an agent's rulebase engine. AlertMonitorEvents, therefore, can be considered to have two logical sources: • The rulebase that generated them (See RuleBaseMonitorEvent on page 110). • The agent that rulebase is loaded on (See PostAlertEvent on page 106).

Method Name Method Format Page Summary AlertMonitorEvent.get...() Returns information about the alert. Methods 97 Accessors are: getAlertID() getRuleBaseEngineState() getTimeGenerated()

AlertMonitorEvent.RuleBase Returns true if this event caused a change in 98 EngineStateChanged() the state of the rulebase engine of the agent from which it originated.

AlertMonitorEvent.RuleBase Returns true if this event caused a change in 99 StateChanged() the state of the rulebase that generated it.

See Also PostAlertEvent, page 106 AgentInstance, page 68 AlertMonitorListener, page 43 ClearAlertEvent, page 100 MonitorEvent, page 105 PostAlertEvent, page 106 RuleBaseMonitorEvent, page 110

TIBCO Hawk Console API Reference AlertMonitorEvent.get...() Accessors | 97

AlertMonitorEvent.get...() Accessors Accessors

Declaration public long getAlertID() public int getRuleBaseEngineState() public long getTimeGenerated()

Purpose Returns information about the alert

Method . Name Description Summary getAlertID() Returns the alert ID associated with this event.

getRuleBaseEngineState() Returns rulebase engine state at the time this event was generated. Rulebase states may be mapped with the constants defined in the interface AlertState.

getTimeGenerated() Returns the time this event was generated, relative to the source agent's system clock.

See Also AlertState, page 46

TIBCO Hawk Console API Reference 98 | Chapter 6 Hawkeye Package Classes

AlertMonitorEvent.RuleBaseEngineStateChanged() Method

Declaration public boolean ruleBaseEngineStateChanged()

Purpose Returns true if this event caused a change in the state of the rulebase engine of the agent from which it originated.

Remarks The rulebase engine's state is defined as the highest alert state of all the currently loaded and active rulebases. Because an AlertMonitorEvent can change the state of a rulebase, it may also affect the state of the rulebase engine.

TIBCO Hawk Console API Reference AlertMonitorEvent.RuleBaseStateChanged() | 99

AlertMonitorEvent.RuleBaseStateChanged() Method

Declaration public boolean ruleBaseStateChanged()

Purpose Returns true if this event caused a change in the state of the rulebase that generated it.

Remarks The alert state of a rulebase is the highest alert state of all of its still active (that is, not cleared) posted alerts.

Only AlertMonitorEvents may change the state of a rulebase. A PostAlertEvent can potentially increase the alert state of a rulebase. A ClearAlertEvent can potentially decrease the alert state of a rulebase.

TIBCO Hawk Console API Reference 100 | Chapter 6 Hawkeye Package Classes

ClearAlertEvent Class

Package COM.TIBCO.hawk.console.hawkeye

Declaration public class ClearAlertEvent extends AlertMonitorEvent

Purpose ClearAlertEvents are generated when a rulebase loaded in the agent's rulebase engine sends a clear event.

Method Name Purpose Page Summary ClearAlertEvent.getReason Gets reason an event was cleared (String). -- ClearedText()

ClearAlertEvent.match() Given a PostAlertEvent, returns true if this 101 ClearAlertEvent matches or "clears" the previously posted alert.

See Also AlertMonitorEvent, page 96 AlertMonitorListener, page 43 PostAlertEvent, page 106

TIBCO Hawk Console API Reference ClearAlertEvent.match() | 101

ClearAlertEvent.match() Method

Declaration public boolean match( PostAlertEvent p)

Purpose Given a PostAlertEvent, returns true if this ClearAlertEvent matches or clears the previously posted alert.

Remarks A ClearAlertEvent will match a PostAlertEvent if they both have the same AgentInstance source and the same alert ID.

A single ClearAlertEvent can match multiple PostAlertEvents if they are duplicate alerts.

Parameters Name Description

p Name of the PostAlertEvent with which to compare this ClearAlertEvent.

See Also AlertMonitorListener, page 43 PostAlertEvent, page 106

TIBCO Hawk Console API Reference 102 | Chapter 6 Hawkeye Package Classes

ErrorExceptionEvent Class

Package COM.TIBCO.hawk.console.hawkeye

Declaration public class ErrorExceptionEvent extends ExceptionEvent

Description Returns information on error exception events.

Method Name Description Summary ErrorExceptionEvent.get Retrieves the ConsoleError that caused this event. ConsoleError() Equivalent to ConsoleError.getConsoleException().

See Also ExceptionEvent, page 103 ConsoleError, page 122

TIBCO Hawk Console API Reference ExceptionEvent | 103

ExceptionEvent Class

Package COM.TIBCO.hawk.console.hawkeye

Declaration public class ExceptionEvent extends EventObject

Purpose Gets information on console exception events.

Method Name Description Summary ExceptionEvent.getConsole Returns ConsoleException events generated by the Exception() console.

ConsoleException, page 123

TIBCO Hawk Console API Reference 104 | Chapter 6 Hawkeye Package Classes

MicroAgentListMonitorEvent Class

Package COM.TIBCO.hawk.console.hawkeye

Declaration public class MicroAgentListMonitorEvent extends MonitorEvent

Purpose A MicroAgentListMonitorEvent object is generated when an agent's list of currently loaded microagents is found to have changed (i.e., when microagents are added or removed). It identifies the particular microagent on a particular agent instance to which the event pertains.

Remarks The source of the event is the AgentInstance object that identifies the particular agent from which the event logically originated.

Method Name Description Summary MicroAgentListMonitor.get Returns the MicroAgentID object identifying MicroAgentID() the specific microagent this event relates to.

See Also PostAlertEvent, page 106 AgentInstance, page 68 MicroAgentID, page 182 MicroAgentListMonitorListener, page 50 MonitorEvent, page 105

TIBCO Hawk Console API Reference MonitorEvent | 105

MonitorEvent Class

Package COM.TIBCO.hawk.console.hawkeye

Declaration public class MonitorEvent extends EventObject

Purpose The root class for all monitoring-related console events.

Remarks The sub-classes of MonitorEvent include:

•AgentMonitorEvent

• MicroAgentListMonitorEvent

• RuleBaseMonitorEvent

All MonitorEvent objects pertain to individual agents and are used to track agent status.

The source of the event will always be the AgentInstance object that identifies the particular agent from which the event logically originated.

Method Name Description Summary MonitorEvent.getAgentInstance() Identifies the agent instance associated with this event and returns the event source cast to AgentInstance.

\

See Also AgentInstance, page 68 AgentMonitorEvent, page 93 AlertMonitorEvent, page 96 MicroAgentListMonitorEvent, page 104 MicroAgentListMonitorListener, page 50 MonitorListener, page 53 RuleBaseMonitorEvent, page 110

TIBCO Hawk Console API Reference 106 | Chapter 6 Hawkeye Package Classes

PostAlertEvent Class

Package COM.TIBCO.hawk.console.hawkeye

Declaration public class PostAlertEvent extends AlertMonitorEvent

Purpose PostAlertEvents are generated when a rulebase loaded in the agent's rulebase engine sends an alert. A PostAlertEvent is said to be "active" until cleared by a corresponding ClearAlertEvent. (See AlertMonitorListener for more details.)

Method Name Description Page Summary PostAlertEvent.get...() Accessors to return information about the alert. 107 Accessors Methods are: getAlertState() getAlertText() getProperties()

PostAlertEvent.isRetrans Indicates whether or not this PostAlertEvent 108 mittedAlert() represents a retransmitted alert.

See Also: AlertMonitorEvent, page 96 AlertMonitorListener, page 43 ClearAlertEvent, page 100

TIBCO Hawk Console API Reference PostAlertEvent.get...() Accessors | 107

PostAlertEvent.get...() Accessors Accessors

Declaration public int getAlertState() public String getAlertText() public Properties getProperties()

Purpose Returns information about the alert.

Remarks The getProperties() method contains various properties of the alert, including:

• Rule: The rule that generated this alert.

• Test: The test that generated this alert.

• DataSource: The data source used by the test to generate this alert.

• DataIndex: The data index used by the test to generate this alert.

• Action: The specific test's action that generated this alert

Method . Name Description Summary getAlertState() Returns the alert state. Alert states should be mapped by the constants defined in the AlertState interface.

getAlertText() Returns the alert text.

getProperties() Returns the alert properties. See Remarks.

See Also AlertState, page 46

TIBCO Hawk Console API Reference 108 | Chapter 6 Hawkeye Package Classes

PostAlertEvent.isRetransmittedAlert() Method

Declaration public boolean isRetransmittedAlert()

Purpose Indicates whether or not this PostAlertEvent represents a retransmitted alert. Retransmitted alerts are delivered as a result of a call to AgentInstance.retransmitAlerts().

PostAlertEvents are delivered to AlertMonitorListener objects. Depending on your application, retransmitted alerts could require special handling. (See AlertMonitorListener for more details.)

See Also AgentInstance, page 68 AlertMonitorListener, page 43

TIBCO Hawk Console API Reference RuleBaseListMonitorEvent | 109

RuleBaseListMonitorEvent Class

Package COM.TIBCO.hawk.console.hawkeye

Declaration public class RuleBaseListMonitorEvent extends RuleBaseMonitorEvent

Purpose A RuleBaseListMonitorEvent object is generated when an agent's list of currently loaded rulebases is found to have changed, that is, when rulebases are added or removed from the agent's rulebase engine. It identifies the particular rulebase on a particular agent instance, to which the event pertains.

Remarks The source of the event is the AgentInstance object that identifies the particular agent from which the event logically originated. The rulebase this event pertains to is identified by the inherited MonitorEvent.getRuleBaseStatus() method.

See Also PostAlertEvent, page 106 RuleBaseMonitorEvent, page 110 AgentInstance, page 68

TIBCO Hawk Console API Reference 110 | Chapter 6 Hawkeye Package Classes

RuleBaseMonitorEvent Class

Package COM.TIBCO.hawk.console.hawkeye

Declaration public class RuleBaseMonitorEvent extends MonitorEvent

Purpose The root class for all rulebase related events, this class identifies the particular rulebase on a particular agent instance to which the event pertains.

The sub-classes of RuleBaseMonitorEvent include: • RuleBaseListMonitorEvent • AlertMonitorEvent

The source of the event is the AgentInstance object that identifies the particular agent from which the event logically originated.

Method Name Description Summary RuleBaseMonitorEvent.get Returns the RuleBaseStatus object identifying the RuleBaseStatus() specific rulebase this event relates to.

See Also AgentInstance, page 68 AlertMonitorEvent, page 96 PostAlertEvent, page 106 RuleBaseMonitorListener, page 59 RuleBaseListMonitorEvent, page 109 RuleBaseStatus, page 111

TIBCO Hawk Console API Reference RuleBaseStatus | 111

RuleBaseStatus Class

Package COM.TIBCO.hawk.console.hawkeye

Declaration public class RuleBaseStatus extends Object

Purpose Returns information about the rulebase and its status.

Method Name Description Page Summary RuleBaseStatus.get...() Accessors Return information about rulebase and 112 status. Methods are: getAlertIDs() getChecksum() getName() getState()

See Also RuleBaseListMonitorEvent, page 109

TIBCO Hawk Console API Reference 112 | Chapter 6 Hawkeye Package Classes

RuleBaseStatus.get...() Accessors Accessors

Declaration public long[] getAlertIDs() public long getChecksum() public String getName() public int getState()

Purpose Returns information about the rulebase and its status

Method . Name Description Summary getAlertIDs() Returns the IDs of the alerts associated with this rulebase. These identify the alerts that were active (non-cleared) at the time this RuleBaseStatus object was created.

getChecksum() Returns the checksum of the rulebase.

getName() Returns name of the rulebase.

getState() Returns the alert state of the rulebase.

See Also AlertState, page 46

TIBCO Hawk Console API Reference TIBHawkConsole | 113

TIBHawkConsole Class

Package COM.TIBCO.hawk.console.hawkeye

Declaration class TIBHawkConsole extends Object

Purpose The TIBHawkConsole provides access to services that can be used for monitoring and management of TIBCO Hawk agent events.

Method Name Description Page Summary TIBHawkConsole.TIBHawk Constructs a TIBHawkConsole object. 114 Console()

TIBHawkConsole.getAgent Returns the AgentManager object. The 116 Manager() agent manager may be used to interact with TIBCO Hawk agents and their microagents.

TIBHawkConsole.getAgent The agent monitor may be used to listen to 117 Monitor() TIBCO Hawk Agent monitoring events.

TIBHawkConsole.setCharact Sets the character encoding used by the 118 erEncoding() TIBCO Rendezvous daemon.

TIBCO Hawk Console API Reference 114 | Chapter 6 Hawkeye Package Classes

TIBHawkConsole.TIBHawkConsole() Constructor

Declaration public TIBHawkConsole( String hawkDomain, String rvService, String rvNetwork, String rvDaemon)

public TIBHawkConsole( String hawkDomain, String serverURL)

public TIBHawkConsole( String hawkDomain, String serverURL, String userName, String password, Hashtable sslParameters)

Purpose Constructs a TIBHawkConsole object.

Remarks The parameters set up the console's communications channels. To be able to communicate with the agents, the hawkDomain parameter must be the same as the TIBCO Hawk domain parameter used by the agents.

If using TIBCO Rendezvous to communicate with the agents, the rvService parameter must be the same as the TIBCO Rendezvous service configuration parameters used by the agents.

Parameters Name Description hawkDomain The TIBCO Hawk domain on which the console is to communicate.

rvService The TIBCO Rendezvous service parameter to use for console communication. See the TIBCO Rendezvous documentation for more information.

rvNetwork The TIBCO Rendezvous network parameter to use for console communication. See the TIBCO Rendezvous documentation for more information.

rvDaemon The TIBCO Rendezvous daemon parameter to use for console communication. See the TIBCO Rendezvous documentation for more information.

serverURL The location of the EMS server. For example, tcp://server1:7222

TIBCO Hawk Console API Reference TIBHawkConsole.TIBHawkConsole() | 115

Name Description userName A valid username defined on the EMS server. password The password for a valid username defined on the EMS server. sslParameters Refer to the TIBCO Enterprise Message Service documentation for details on the SSL paremeters that can be set by this paremeter.

If the EMS server has authentication disabled, the specified username and password fields are ignored.

TIBCO Hawk Console API Reference 116 | Chapter 6 Hawkeye Package Classes

TIBHawkConsole.getAgentManager() Constructor

Declaration public AgentManager getAgentManager()

Purpose Returns the agent manager.

Remarks The agent monitor may be used to listen to TIBCO Hawk agent monitoring events.

TIBCO Hawk Console API Reference TIBHawkConsole.getAgentMonitor() | 117

TIBHawkConsole.getAgentMonitor() Constructor

Declaration public AgentMonitor getAgentMonitor()

Purpose Returns the agent monitor.

Remarks The agent manager may be used to interact with TIBCO Hawk agents and their microagents.

TIBCO Hawk Console API Reference 118 | Chapter 6 Hawkeye Package Classes

TIBHawkConsole.setCharacterEncoding() Method

Declaration public void setCharacterEncoding(java.lang.String encoding)

Purpose Sets the character encoding used by the TIBCO Rendezvous daemon.

Remarks If required, it is recommended that this method be called before accessing either AgentMonitor or AgentManager. The argument should match the character_encoding value passed to that agent.

Throws java.io.UnsupportedEncodingException. See the TIBCO Rendezvous documentation.

TIBCO Hawk Console API Reference WarningExceptionEvent | 119

WarningExceptionEvent Class

Package COM.TIBCO.hawk.console.hawkeye

Declaration public class WarningExceptionEvent extends ExceptionEvent

Purpose Delivers information on exception events.

Method Name Description Summary WarningExceptionEvent.get Retrieves the ConsoleWarning that caused this ConsoleWarning() event. This method is equivalent to ConsoleWarning.getConsoleException().

See Also ConsoleWarning, page 125 ExceptionEvent, page 103 WarningExceptionListener, page 60

TIBCO Hawk Console API Reference 120 | Chapter 6 Hawkeye Package Classes

TIBCO Hawk Console API Reference | 121

Chapter 7 Hawkeye Package Exception Classes

This chapter describes the COM.TIBCO.hawk.console.hawkeye package exception classes and its methods.

Topics

• ConsoleError, page 122 • ConsoleException, page 123 • ConsoleInitializationException, page 124 • ConsoleWarning, page 125

TIBCO Hawk Console API Reference 122 | Chapter 7 Hawkeye Package Exception Classes

ConsoleError Class

Package COM.TIBCO.hawk.console.hawkeye

Declaration public class ConsoleError extends ConsoleException

Purpose Delivered asynchronously in ErrorEvents when the console encounters a critical error.

See Also ConsoleException, page 123

TIBCO Hawk Console API Reference ConsoleException | 123

ConsoleException Class

Package COM.TIBCO.hawk.console.hawkeye

Declaration public class ConsoleException extends Exception

Purpose The superclass of all checked exceptions thrown or delivered by the TIBHawkConsole.

See Also AgentPlatform, page 94

TIBCO Hawk Console API Reference 124 | Chapter 7 Hawkeye Package Exception Classes

ConsoleInitializationException Class

Package COM.TIBCO.hawk.console.hawkeye

Declaration public class ConsoleInitializationException extends ConsoleException

Purpose Thrown when there is an error during console initialization.

See Also ConsoleException, page 123

TIBCO Hawk Console API Reference ConsoleWarning | 125

ConsoleWarning Class

Package COM.TIBCO.hawk.console.hawkeye

Declaration public class ConsoleWarning extends ConsoleException

Purpose Delivered asynchronously in WarningEvents when the console encounters a warning condition.

See Also ConsoleException, page 123

TIBCO Hawk Console API Reference 126 | Chapter 7 Hawkeye Package Exception Classes

TIBCO Hawk Console API Reference | 127

Chapter 8 Talon Package Interfaces

This chapter describes the COM.TIBCO.hawk.console.talon package interface classes and its methods.

Topics

• MicroAgentServer, page 128 • OpenData, page 133 • Subscription, page 134 • SubscriptionHandler, page 137

TIBCO Hawk Console API Reference 128 | Chapter 8 Talon Package Interfaces

MicroAgentServer Interface

Package COM.TIBCO.hawk.talon

Declaration public interface MicroAgentServer

Purpose The MicroAgentServer interface. MicroAgentServer objects interact with an agent's microagents.

Method Name Description Page Summary MicroAgentServer.describe() Returns a descriptor for a 129 microagent.

MicroAgentServer.getMicroAgentIDs() Returns an array identifying all 130 microagents that have the supplied name.

MicroAgentServer.invoke() Performs a method invocation on 131 a microagent.

MicroAgentServer.subscribe() Registers a subscription with a 132 microagent.

TIBCO Hawk Console API Reference MicroAgentServer.describe() | 129

MicroAgentServer.describe() Method

Declaration public abstract MicroAgentDescriptor describe( MicroAgentID id) throws MicroAgentException

Purpose This method returns a descriptor for a microagent or null if the descriptor is not available.

Remarks The descriptor describes the microagent and all of its methods. It is required in order to properly construct and perform method invocations and subscription against a microagent.

Throws IllegalArgumentException if the argument is null or empty string.

Throws MicroAgentException if a problem occurred servicing this request.

Parameters Name Description id The microagent ID of the microagent to describe.

See Also MicroAgentException, page 196

TIBCO Hawk Console API Reference 130 | Chapter 8 Talon Package Interfaces

MicroAgentServer.getMicroAgentIDs() Method

Declaration public abstract MicroAgentID[] getMicroAgentIDs( String name) throws MicroAgentException

Purpose Queries the MicroAgentServer to learn the id of all microagents matching the supplied name. Returns a list of MicroAgentID objects identifying all microagents bearing that name that were discovered to be running on all agents.

Remarks Throws MicroAgentException if a problem occurred servicing this request.

Parameters Name Description name The microagent name.

See Also MicroAgentException, page 196

TIBCO Hawk Console API Reference MicroAgentServer.invoke() | 131

MicroAgentServer.invoke() Method

Declaration public abstract MicroAgentData invoke( MicroAgentID id, MethodInvocation mi) throws MicroAgentException

Purpose Performs a method invocation on a microagent.

Remarks The results of the invocation are delivered in the data field of the MicroAgentData return. Two general types of errors can occur with method invocations: 1. During the delivery of a method invocation to, or the results back from, a microagent. This condition will cause this method to throw a MicroAgentException. 2. During the invocation of the method on the microagent itself. This condition will cause this method to deliver a MicroAgentException in the data field of the MicroAgentData return. Thus, a successful method invocation is one that doesn't throw an exception and does not deliver a MicroAgentException in the data field of its MicroAgentData return.

If the method invocation is successful, the data field of its MicroAgentData return will contain the method's return value or null if the method doesn't return a value. You should not invoke to methods that are non-open (proprietary) unless you have supporting API and documentation. Doing so will have unpredictable results. Whether or not a method is open is defined by its MethodDescriptor.

Throws IllegalArgumentException if the parameter conditions are violated.

Throws MicroAgentException if an error occurs during the delivery of a method invocation to, or the results back from, a microagent.

Parameters Name Description id The microagent ID of the target microagent.

mi The MethodInvocation object identifying the method to be invoked and its arguments. May not be null.

See Also MicroAgentException, page 196 MethodDescriptor, page 161

TIBCO Hawk Console API Reference 132 | Chapter 8 Talon Package Interfaces

MicroAgentServer.subscribe() Method

Declaration public abstract Subscription subscribe( MicroAgentID id, MethodSubscription msub, SubscriptionHandler handler, Object handBack) throws MicroAgentException

Purpose Registers a subscription with a microagent.

Remarks Subscriptions are made against microagent methods. Registering a subscription is analogous to registering for events, where a microagent's method is the event source. The subscribed-to data is delivered asynchronously to the supplied SubscriptionHandler. Two general types of errors can occur with method invocations: 1. During the registration of the subscription. This condition will cause this method to throw a MicroAgentException. 2. During the servicing of the subscription. These errors are delivered to the SubscriptionHandler.

Throws IllegalArgumentException if the parameter conditions are violated.

Throws MicroAgentException if a problem occurred servicing this request.

Parameters Name Description id The microagent ID of the target microagent.

msub Identifies what is being subscribed to.

handler The object that handles subscription results.

handback This Object parameter is accessible in the resulting Subscription object which is delivered to the handler along with subscription results.

See Also MicroAgentException, page 196

TIBCO Hawk Console API Reference OpenData | 133

OpenData Interface

Package COM.TIBCO.hawk.talon

Declaration public interface OpenData

Purpose This interface identifies the open data types. They are: • java.lang.String • java.lang.Character • java.lang.Boolean • java.lang.Byte • java.lang.Short • java.lang.Integer • java.lang.Long • java.lang.Float • java.lang.Double • COM.TIBCO.hawk.talon.CompositeData* • COM.TIBCO.hawk.talon.TabularData*

CompositeData and TabularData are also referred to as the aggregate open data types.

Method Name Syntax Description Summary types public static final String types[] An array of strings of the fully-qualified names of the open data types.

TIBCO Hawk Console API Reference 134 | Chapter 8 Talon Package Interfaces

Subscription Interface

Package COM.TIBCO.hawk.talon

Declaration public interface Subscription

Purpose Subscription objects are returned as a result of registering a method subscription.

Method Name Description Page Summary Subscription.cancel() Used to cancel the subscription. 135

Subscription.get...() Accessors Return information on subscription objects, 136 returned as a result of registering a method subscription. Methods are: getHandBack() getMethodSubscription() getMicroAgentID()

See Also MicroAgentServer.subscribe(), page 132

TIBCO Hawk Console API Reference Subscription.cancel() | 135

Subscription.cancel() Method

Declaration public abstract void cancel()

Purpose Used to cancel the subscription.

TIBCO Hawk Console API Reference 136 | Chapter 8 Talon Package Interfaces

Subscription.get...() Accessors Accessors

Declaration public abstract Object getHandback() public abstract MethodSubscription getMethodSubscription() public abstract MicroAgentID getMicroAgentID()

Purpose Return information on subscription objects, returned as a result of registering a method subscription

Method . Name Description Summary getHandBack() Returns the handback parameter used when the subscription was registered.

getMethodSubscription() Returns the MethodSubscription object used when the subscription was registered.

getMicroAgentID() Returns the microagent ID used when the subscription was registered.

See Also MethodSubscription, page 171 MicroAgentID, page 182

TIBCO Hawk Console API Reference SubscriptionHandler | 137

SubscriptionHandler Interface

Package COM.TIBCO.hawk.talon

Declaration public interface SubscriptionHandler

Purpose SubscriptionHandler objects are used as parameters to MicroAgentServer.subscribe() They handle the subscription results.

Remarks Each of the methods in this interface behaves as a message callback function, processing each message as it arrives. As with all asynchronous callback functions, your implementations of these methods must return promptly, and must not block. If any of these methods must compute at length, we recommend that it spawn a separate thread to complete its task. If any of these methods accesses shared data, you must protect against access collision by synchronizing.

Method Name Description Page Summary SubscriptionHandler.on Receives the data for a particular subscription. 138 Data()

SubscriptionHandler.on Called when an error causes an interruption in 139 Error() the servicing of a subscription.

SubscriptionHandler.on Called when there is no longer an error condition 140 ErrorCleared() which is interrupting service.

SubscriptionHandler.on Called when an error condition causes the 141 Termination() subscription to be terminated.

TIBCO Hawk Console API Reference 138 | Chapter 8 Talon Package Interfaces

SubscriptionHandler.onData() Method

Declaration public abstract void onData( Subscription s, MicroAgentData data)

Purpose This method receives the data for a particular subscription.

Parameters Name Description

s The Subscription object generated when the subscription was made.

data The data produced by the Microagent.

See Also MicroAgentData, page 176 Subscription, page 134

TIBCO Hawk Console API Reference SubscriptionHandler.onError() | 139

SubscriptionHandler.onError() Method

Declaration public abstract void onError( Subscription s, MicroAgentException e)

Purpose This method is called when an error causes an interruption in the servicing of a subscription.

Remarks Once called, this handler will not receive any more data until SubscriptionHandler.onErrorCleared() is called.

Parameters Name Description

s The Subscription object generated when the subscription was made.

e An exception identifying the error.

See Also MicroAgentException, page 196 Subscription, page 134 SubscriptionHandler.onErrorCleared(), page 140

TIBCO Hawk Console API Reference 140 | Chapter 8 Talon Package Interfaces

SubscriptionHandler.onErrorCleared() Method

Declaration public abstract void onErrorCleared( Subscription s)

Purpose This method is called when there is no longer an error condition which is interrupting service. It indicates that this subscription can continue to receive data.

Parameters Name Description

s The Subscription object generated when the subscription was made.

See Also Subscription, page 134

TIBCO Hawk Console API Reference SubscriptionHandler.onTermination() | 141

SubscriptionHandler.onTermination() Method

Declaration public abstract void onTermination( Subscription s, MicroAgentException e)

Purpose This method is called when an error condition causes the subscription to be terminated.

Parameters Name Description

s The Subscription object generated when the subscription was made.

e An exception identifying the error condition that caused the termination.

See Also MicroAgentException, page 196 Subscription, page 134

TIBCO Hawk Console API Reference 142 | Chapter 8 Talon Package Interfaces

TIBCO Hawk Console API Reference | 143

Chapter 9 Talon Package Classes

This chapter describes the COM.TIBCO.hawk.console.talon package classes and its methods.

Topics

• Agent, page 144 • CompositeData, page 145 • CompositeDataDescriptor, page 148 • DataDescriptor, page 151 • DataElement, page 159 • MethodDescriptor, page 161 • MethodInvocation, page 169 • MethodSubscription, page 171 • MicroAgentData, page 176 • MicroAgentDescriptor, page 178 • MicroAgentID, page 182 • TabularData, page 184 • TabularDataDescriptor, page 190

TIBCO Hawk Console API Reference 144 | Chapter 9 Talon Package Classes

Agent Class

Package COM.TIBCO.hawk.talon

Declaration public class Agent extends Object implements Serializable

Purpose Agent objects are used to identify microagents.

Method Name Description Summary Agent.getDns() This String gets the DNS entry for this agent.

Agent.getHawkDomain() This String gets the TIBCO Hawk domain name of this agent.

Agent.getName() This String gets the name of this agent.

Agent.getStartTime() This long gets the time the agent was initialized, from the perspective of the system clock on the host the agent is running on. This value is the number of milliseconds since January 1, 1970, 00:00:00 GMT.

Agent.toString() Returns the String representation of this Agent object.

TIBCO Hawk Console API Reference CompositeData | 145

CompositeData Class

Package COM.TIBCO.hawk.talon

Declaration public class CompositeData extends Object implements Serializable

Purpose This is an open data type used to build aggregates.

Method Name Description Page Summary CompositeData.CompositeData() Constructs a CompositeData object 146 from an array of DataElement objects.

CompositeData.get...() Accessors Return DataElements and value of 147 this element. Methods are: getDataElements() getValue()

CompositeData.toString() Returns a String representation of the — composite data object.

See Also DataElement, page 159 OpenData, page 133

TIBCO Hawk Console API Reference 146 | Chapter 9 Talon Package Classes

CompositeData.CompositeData() Constructor

Declaration public CompositeData( DataElement data[])

Purpose Constructs a CompositeData object from an array of DataElement objects.

Remarks Throws IllegalArgumentException if the parameter conditions are violated.

Parameters Name Description

data An array of DataElement objects. May not be null or empty array. Must have at least one element. The array may not contain null elements. All DataElement objects must have unique names. All DataElement values must be of an open data type (as identified by the OpenData interface), or null.

See Also CompositeDataDescriptor, page 148 DataElement, page 159 OpenData, page 133

TIBCO Hawk Console API Reference CompositeData.get...() Accessors | 147

CompositeData.get...() Accessors Accessors

Declaration public DataElement[] getDataElements() public Object getValue()

Purpose Return DataElements and value of this element

Method . Name Description Summary getDataElements() Returns an array containing the same DataElement objects, but not necessarily in the same order, used to construct this object.

getValue() Returns the value of the named element. Null if named element has a null value or if the named element is not found.

TIBCO Hawk Console API Reference 148 | Chapter 9 Talon Package Classes

CompositeDataDescriptor Class

Package COM.TIBCO.hawk.talon

Declaration public class CompositeDataDescriptor extends DataDescriptor

Purpose This subclass of DataDescriptor is used to describe objects of type CompositeData.

Remarks The value returned by the getElementDescriptors() method describes all the elements in the composite. Default value, legal value choices, and value choices are not supported for CompositeDataDescriptor.

Method Name Description Page Summary CompositeDataDescriptor.Composite Constructs a 149 DataDescriptor() CompositeDataDescriptor object.

CompositeDataDescriptor.getElement Returns an array of — Descriptors() datadescriptors of the aggregated elements.

CompositeDataDescriptor.isOpenData Returns true if this descriptor 150 () describes an open data type.

CompositeDataDescriptor.toString() Returns the String representation of — this descriptor.

See Also CompositeData, page 145 DataDescriptor, page 151

TIBCO Hawk Console API Reference CompositeDataDescriptor.CompositeDataDescriptor() | 149

CompositeDataDescriptor.CompositeDataDescriptor() Constructor

Declaration public CompositeDataDescriptor( String name, String desc, DataDescriptor elementDescriptors[])

Purpose Constructs a CompositeDataDescriptor object.

Parameters Name Description name The name of the data parameter being described. It must be a non-null, non-empty alphanumeric string.

desc A description of the parameter being described.

elementDescriptors An array of descriptors describing the components of the CompositeData. It must contain DataDescriptor objects that describe only open data types. All elements must have unique names. It can not be null or empty array. The array can not contain null elements.

See Also DataDescriptor, page 151 CompositeData, page 145

TIBCO Hawk Console API Reference 150 | Chapter 9 Talon Package Classes

CompositeDataDescriptor.isOpenData() Method

Declaration public boolean isOpenData()

Purpose Returns true if this descriptor describes an open data type.

Remarks This overridden method will always return true for this subclass of DataDescriptor because the constructor insures that only the open data type CompositeData may be described.

Overrides isOpenData in class DataDescriptor.

See Also DataDescriptor.isOpenData(), page 158

TIBCO Hawk Console API Reference DataDescriptor | 151

DataDescriptor Class

Package COM.TIBCO.hawk.talon

Declaration public class DataDescriptor extends Object implements Serializable

Purpose Describes a data object which is used as either an argument parameter or return parameter in a MethodDescriptor.

Remarks Only Serializable reference types may be described. The data being described by this class and its subclasses is considered to be open data if it is one of the types defined by the OpenData interface. The aggregate open data types must be described with the corresponding subclasses of this class in order to be treated as open:

• CompositeData should be described with CompositeDataDescriptor.

• TabularData should be described with TabularDataDescriptor.

Using DataDescriptor to describe these types is legal. However, it will result in the isOpenData() method returning false.

The attributes accessed by the methods getDefault(), getLegalValueChoices(), and getValueChoices() can be of a type whose class is not guaranteed to be available on all virtual machines. To insure they can be safely transmitted between virtual machines, they are internally stored in serialized form. As a result, several of the methods of this class throw serialization related exceptions.

Method Name Description Page Summary DataDescriptor.DataDescriptor( Constructs a DataDescriptor object. 153 )

DataDescriptor.getDefault() Returns a default value for this parameter. 155

DataDescriptor.getDescription() Returns a description of this parameter — (String).

DataDescriptor.getLegalValueC Lists the legal values for the described 156 hoices() parameter.

DataDescriptor.getName() Returns the name of the described — parameter (String).

TIBCO Hawk Console API Reference 152 | Chapter 9 Talon Package Classes

Name (Cont’d) Description (Cont’d) Page DataDescriptor.getType() Returns the fully-qualified class name of — the described parameter (String).

DataDescriptor.getValueChoices Lists the possible values for the described 157 parameter.

DataDescriptor.isOpenData() Returns true if the data object being 158 described is typed (see getType()) to be one of the non-aggregate open data types defined in the OpenData interface.

DataDescriptor.toString() Returns the String representation of this — DataDescriptor object.

See Also CompositeDataDescriptor, page 148 OpenData, page 133 TabularDataDescriptor, page 190

TIBCO Hawk Console API Reference DataDescriptor.DataDescriptor() | 153

DataDescriptor.DataDescriptor() Constructor

Declaration public DataDescriptor( String name, Class c, String desc)

public DataDescriptor( String name, Class c, String desc, Object def, Object leg[], Object val[]) throws IOException

Purpose Constructs a DataDescriptor object. It may be constructed to describe any serializable reference data type.

The first form constructs a DataDescriptor with only the required fields. The second form uses additional optional fields.

Throws IllegalArgumentException if the parameter conditions are violated. Throws IOException if a problem occurs during serialization of def, leg, or val.

Parameters Name Description name The name of the data parameter being described. It must be a non-null, non-empty alphanumeric string. Note: The use of curly brackets { } in microagent method parameter names is not supported. Use of these characters results in an error.

c A class object representing the class type of the parameter being described. It must represent a reference type that is Serializable.

desc A description of the parameter being described.

def A default value that may be used for the parameter. Null indicates that a default is not specified. If non-null, def must be of a type assignable to that represented by the type argument.

leg An array of legal values for this parameter. It indicates the only values this parameter may have. Null or empty array indicates that the legal values are not specified. If non-null, the array elements must all be of a type assignable to that represented by the type argument.

TIBCO Hawk Console API Reference 154 | Chapter 9 Talon Package Classes

Name Description val An array of possible values for this parameter. Null or empty array indicates that the possible values are not specified. If non-null, the array elements must all be of a type assignable to that represented by the type argument.

TIBCO Hawk Console API Reference DataDescriptor.getDefault() | 155

DataDescriptor.getDefault() Method

Declaration public Object getDefault() throws ClassNotFoundException, IOException

Purpose Returns a default value for this parameter. A return of null indicates that no default has been specified.

Remarks When this class is used to describe a method argument parameter, this value represents a valid default value. This value has not been assigned any semantics when this class is used to describe a method return parameter. The exceptions thrown by this method relate to the fact that this value is internally stored in a serialized form. They normally should not occur when dealing with open-data types.

Throws ClassNotFoundException if the class represented by getType() cannot be found. This will occur when attempting to access this field for a non-open data type without access to the corresponding class.

Throws IOException if a problem is encountered while deserializing.

TIBCO Hawk Console API Reference 156 | Chapter 9 Talon Package Classes

DataDescriptor.getLegalValueChoices() Method

Declaration public Object[] getLegalValueChoices() throws ClassNotFoundException, IOException

Purpose Returns a list of legal values for the described parameter. A return of null indicates that the legal values have not been specified.

Remarks When this class is used to describe a method argument parameter, this value represents a valid the list of legal values. This value has not been assigned any semantics when this class is used to describe a method return parameter. The exceptions thrown by this method relate to the fact that this value is internally stored in a serialized form. They normally should not occur when dealing with open-data types.

Throws ClassNotFoundException if the class represented by getType() cannot be found. This will occur when attempting to access this field for a non-open data type without access to the corresponding class.

Throws IOException if a problem is encountered while deserializing.

TIBCO Hawk Console API Reference DataDescriptor.getValueChoices | 157

DataDescriptor.getValueChoices Method

Declaration public Object[] getlValueChoices() throws ClassNotFoundException, IOException

Purpose Returns a list of possible values for the described parameter. Note that this does not imply that these are the only values this parameter may take on. A return of null indicates that the possible values have not been specified.

Remarks When this class is used to describe a method argument parameter, this value represents a valid the list of legal values. This value has not been assigned any semantics when this class is used to describe a method return parameter. The exceptions thrown by this method relate to the fact that this value is internally stored in a serialized form. They normally should not occur when dealing with open-data types.

Throws ClassNotFoundException if the class represented by getType() cannot be found. This will occur when attempting to access this field for a non-open data type without access to the corresponding class.

Throws IOException if a problem is encountered while deserializing.

TIBCO Hawk Console API Reference 158 | Chapter 9 Talon Package Classes

DataDescriptor.isOpenData() Method

Declaration public boolean isOpenData()

Purpose Returns true if the data object being described is typed (see DataDescriptor.getType() on page 152) to be one of the non-aggregate open data types defined in the OpenData interface.

Remarks In order for the aggregate open data types CompositeData and TabularData to be treated as open data, they must be described by their corresponding descriptor classes CompositeDataDescriptor and TabularDataDescriptor.

See Also CompositeDataDescriptor, page 148 OpenData, page 133 TabularDataDescriptor, page 190

TIBCO Hawk Console API Reference DataElement | 159

DataElement Class

Package COM.TIBCO.hawk.talon

Declaration public class DataElement extends Object implements Serializable

Purpose Used to represent data objects in name-value pairs.

Method Name Description Page Summary DataElement.DataElement() Constructs a DataElement object. 160

DataElement.getName() Returns the name of this element (as a — String).

DataElement.getValue() Returns the value of this element (as an — Object).

DataElement.toString() Returns a String representation of this — element.

TIBCO Hawk Console API Reference 160 | Chapter 9 Talon Package Classes

DataElement.DataElement() Constructor

Declaration public DataElement( String name, Object value)

Purpose Constructs a DataElement object.

Parameters Name Description name The name of the element. May not be null or empty string.

value The value of the element.

TIBCO Hawk Console API Reference MethodDescriptor | 161

MethodDescriptor Class

Package COM.TIBCO.hawk.talon

Declaration public class MethodDescriptor extends Object implements Serializable

Purpose MethodDescriptor objects are used to describe the methods of microagents.

Remarks Two MethodDescriptor objects are equal if they have the same name, description, return descriptors, argument descriptors (specified in the same order), and the same async and impact values.

Constants Name Description Summary IMPACT_ACTION Syntax: public static final int Indicates that the method takes some action that can potentially change the state of the managed object.

IMPACT_ACTION_INFO Syntax: public static final int Indicates that the method takes some action that can potentially change the state of the managed object and also returns some information as a return value.

IMPACT_INFO Syntax: public static final int Indicates that the method simply retrieves some information in a manner that does not change the state of the managed object.

Method Name Description Page Summary MethodDescriptor.Method Constructs a MethodDescriptor object. 163 Descriptor()

MethodDescriptor.get...() Return information on a method. Methods are: 165 Accessors getArgumentDescriptors() getDescription() getImpact() getMaxResponseTime() getName() getReturnDescriptor()

TIBCO Hawk Console API Reference 162 | Chapter 9 Talon Package Classes

Name (Cont’d) Description (Cont’d) Page MethodDescriptor.isAsync() Returns true if this method is asynchronous. 166

MethodDescriptor.isOpenM Returns true if this descriptor describes an 167 ethod() open method.

MethodDescriptor.toFormat Returns a formatted String representation of 168 tedString() this MethodDescriptor object.

MethodDescriptor.toString() Returns the String representation of this — MethodDescriptor object.

See Also TabularDataDescriptor, page 190

TIBCO Hawk Console API Reference MethodDescriptor.MethodDescriptor() | 163

MethodDescriptor.MethodDescriptor() Constructor

Declaration public MethodDescriptor( String name, String desc, DataDescriptor ret, DataDescriptor args[], boolean async, int impact, int maxTime)

Purpose Constructs a MethodDescriptor object.

Remarks An asynchronous method (see async parameter) is analogous to an event source. Listeners that subscribe to an asynchronous method will receive the method's declared return value each time an particular event occurs. A method may not be declared as asynchronous unless it also describes a return value (see ret parameter).

MaxTime is the number of seconds that must elapse between the method's invocation and its return before declaring it to have timed out. If the method is being invoked remotely, the round-trip time of the intervening transport mechanism should also be taken into account before declaring a timeout.

Throws IllegalArgumentException if the parameter conditions are violated.

Parameters Name Description name The name of the method. Must be a non-null non-empty string.

desc A description of the method.

ret A DataDescriptor describing the return value of the method. It may be null to indicate that this method has no return value.

args An array of DataDescriptor objects describing the arguments required by the method. It may be null or empty array to indicate that this method has no arguments. If not empty, the array must not contain null elements. Each DataDescriptor in this array must have a unique name.

async Indicates whether or not this method is an asynchronous method. (See Remarks.)

TIBCO Hawk Console API Reference 164 | Chapter 9 Talon Package Classes

Name (Cont’d) Description (Cont’d) impact States the impact this method will have. Must be one of IMPACT_ACTION, IMPACT_INFO, or IMPACT_ACTION_INFO. A method that does not return a value (see ret parameter) may not be declared to have an impact of IMPACT_INFO or IMPACT_ACTION_INFO.

maxTime The maximum response time for this method, in seconds. Must be greater than zero. (See Remarks.)

See Also DataDescriptor, page 151

TIBCO Hawk Console API Reference MethodDescriptor.get...() Accessors | 165

MethodDescriptor.get...() Accessors Accessors

Declaration public DataDescriptor[] getArgumentDescriptors() public String getDescription() public int getImpact() public int getMaxResponseTime() public String getName() public DataDescriptor getReturnDescriptor()

Purpose Return information on a method.

Remarks MaxResponseTime is the number of seconds that must elapse between the method's invocation and its return before declaring it to have timed out. If the method is being invoked remotely, the round-trip time of the intervening transport mechanism should also be taken into account before declaring a timeout.

Method Name Description Summary getArgumentDescriptors() Returns a DataDescriptor array describing the method's arguments or null if this method accepts no arguments.

getDescription() Returns a description of this method.

getImpact() Returns the impact of this method. See MethodDescriptor on page 161 for values.

getMaxResponseTime() Returns the maximum response time for this method. See Remarks.

getName() Returns the method name.

getReturnDescriptor() Returns the DataDescriptor describing the method's return value or null if the method returns no value.

See Also DataDescriptor, page 151

TIBCO Hawk Console API Reference 166 | Chapter 9 Talon Package Classes

MethodDescriptor.isAsync() Method

Declaration public boolean isAsync()

Purpose Returns true if this method is asynchronous.

Remarks An asynchronous method is analogous to an event source. Listeners that subscribe to an asynchronous method will receive the method's declared return value each time a particular event occurs.

TIBCO Hawk Console API Reference MethodDescriptor.isOpenMethod() | 167

MethodDescriptor.isOpenMethod() Method

Declaration MethodDescriptor.isOpenMethod()

Purpose Returns true if this descriptor describes an open method.

Remarks An open method is one whose argument and return types are limited to the set of open data types defined by the OpenData interface. Because an open method uses a well known set of types, it can be used in an open manner by any application using this API. Because an open method uses a well known set of types, it can be used in an open manner by any application using this API. A non-open method is a proprietary method from the perspective of the TIBCO Hawk Console API because it uses data types outside of this set. Use of non-open methods is supported by this API. However, this API by itself is not sufficient to use such methods, an additional proprietary API is required.

See Also OpenData, page 133

TIBCO Hawk Console API Reference 168 | Chapter 9 Talon Package Classes

MethodDescriptor.toFormattedString() Method

Declaration public string toFormattedString(String indent)

Purpose Returns a formatted string representation of this descriptor.

Remarks Takes a String object as a parameter. Alternatively, you can use the MethodDescriptor.toString() method, which takes no arguments.

Parameters Name Description

indent A string for padding the formatted output string. For example, to indent the output by 3 spaces, specify " " (three blank spaces).

Specify null to not use indentation.

TIBCO Hawk Console API Reference MethodInvocation | 169

MethodInvocation Class

Package COM.TIBCO.hawk.talon

Declaration public class MethodInvocation extends Object implements Serializable

Purpose This class is used to represent a method invocation.

Remarks A MethodInvocation should be constructed in accordance with the MethodDescriptor of the target method.

Method Name Description Page Summary MethodInvocation.Method Constructs a MethodInvocation object. 170 Invocation()

MethodInvocation.getArgu Returns the array of DataElement objects — ments() representing the method arguments. Returns an empty array if no arguments were provided.

MethodInvocation.getMeth Returns the method name (String). — odName()

MethodInvocation.toString Returns the String representation of this — () MethodInvocation.

See Also DataElement, page 159 MethodDescriptor, page 161 MethodSubscription, page 171

TIBCO Hawk Console API Reference 170 | Chapter 9 Talon Package Classes

MethodInvocation.MethodInvocation() Constructor

Declaration public MethodInvocation String methodName, DataElement args[])

Purpose Constructs a MethodInvocation object.

Parameters Name Description methodName The name of the method. May not be null or empty string.

args An array of DataElement objects representing the arguments of the method. The names and values of these elements should correspond to what was described in the MethodDescriptor for this method. They must be serializable types.

See Also DataElement, page 159 MethodDescriptor, page 161

TIBCO Hawk Console API Reference MethodSubscription | 171

MethodSubscription Class

Package COM.TIBCO.hawk.talon

Declaration public class MethodSubscription extends MethodInvocation

Purpose This class is used to represent a method subscription.

Remarks A MethodSubscription is similar to a MethodInvocation but is used to subscribe to method results. The form of constructor you use depends on whether you are creating a subscription for a synchronous or asynchronous method.

Method Name Description Page Summary MethodSubscription.MethodSubs Used to construct method subscriptions 172 cription() for methods.

MethodSubscription.getInterval() Returns the subscription interval of 174 subscriptions constructed for synchronous methods.

MethodSubscription.isAsync() Returns true if this object was built with 175 the constructor for asynchronous method subscriptions.

MethodSubscription.toString() Returns the String representation of this — MethodSubscription. Overrides MethodInvocation.toString.

See Also MethodInvocation, page 169 MethodDescriptor, page 161

TIBCO Hawk Console API Reference 172 | Chapter 9 Talon Package Classes

MethodSubscription.MethodSubscription() Constructor

Declaration public MethodSubscription( String methodName, DataElement args[], long interval)

public MethodSubscription( String methodName, DataElement args[])

Purpose Used to construct method subscriptions for methods. The constructor you use depends on whether you are creating a subscription for a synchronous (first form) or asynchronous method (second form). (See MethodDescriptor.isAsync(), page 166.)

Remarks A MethodSubscription should be constructed in accordance with the MethodDescriptor of the target method. The form of constructor you use depends on whether you are creating a subscription for a synchronous or asynchronous method. (See MethodDescriptor.isAsync() on page 166.) The first form is a constructor for synchronous method subscriptions. It requires an interval parameter. It is used to specify a desired subscription service rate. Subscriptions made of synchronous methods will use this value as a hint to determine how often to deliver data to service a subscription. Most microagents will usually enforce a minimum rate which will be used if the supplied value is below their minimum. The second form is a constructor for asynchronous method subscriptions. It does not accept an interval parameter. Asynchronous methods deliver data at a rate determined by the microagent, typically, whenever it is available.

Parameters Name Description methodName The name of the method.

args An array of DataElement objects representing the arguments of the method. The names and values of these elements should correspond to what was described in the MethodDescriptor for this method. They must be serializable types.

interval The desired subscription service rate in milliseconds. Must be greater than zero.

See Also DataElement, page 159

TIBCO Hawk Console API Reference MethodSubscription.MethodSubscription() | 173

MethodDescriptor, page 161

TIBCO Hawk Console API Reference 174 | Chapter 9 Talon Package Classes

MethodSubscription.getInterval() Method

Declaration public long getInterval()

Purpose Returns the subscription interval of subscriptions constructed for synchronous methods.

Throws IllegalStateException if isAsync() returns true.

TIBCO Hawk Console API Reference MethodSubscription.isAsync() | 175

MethodSubscription.isAsync() Method

Declaration public boolean isAsync()

Purpose Returns true if this object was built with the constructor for asynchronous method subscriptions.

TIBCO Hawk Console API Reference 176 | Chapter 9 Talon Package Classes

MicroAgentData Class

Package COM.TIBCO.hawk.talon

Declaration public class MicroAgentData extends Object implements Serializable

Purpose Encapsulates data returned by microagent methods.

Method Name Description Page Summary MicroAgentData.MicroAgen Constructs a MicroAgentData object. 177 tData()

MicroAgentData.getData() Returns the generated data (Object). —

MicroAgentData.getSource() Returns the MicroAgentID identifying — the microagent that generated this data.

See Also MicroAgentID, page 182

TIBCO Hawk Console API Reference MicroAgentData.MicroAgentData() | 177

MicroAgentData.MicroAgentData() Constructor

Declaration public MicroAgentData( MicroAgentID source, Object data)

Purpose Constructs a MicroAgentData object.

Parameters Name Description

source The MicroAgentID identifying the microagent.

data The returned data.

See Also MicroAgentID, page 182

TIBCO Hawk Console API Reference 178 | Chapter 9 Talon Package Classes

MicroAgentDescriptor Class

Package COM.TIBCO.hawk.talon

Declaration public class MicroAgentDescriptor extends Object implements Serializable

Purpose This class is used to describe a microagent and its methods.

Remarks MicroAgentDescriptor objects are used by microagents to advertise their supported methods along with all the information required to invoke them. By convention, every microagent should have a globally unique name. If two microagent instances have the same name they should also have the same MicroAgentDescriptor, which implies that they advertise support for the same methods with the same signatures.

Two MicroAgentDescriptor objects are equal if they have the same name, display name, description, and method descriptors. Note that two MicroAgentDescriptors may have the same checksum but not be equal.

Method Name Description Page Summary MicroAgentDescriptor.Micr Constructs a MicroAgentDescriptor 179 oAgentDescriptor() object.

MicroAgentDescriptor.get... Return information on a microagent’s 180 () Accessors description and methods. Methods are: getChecksum() getDescription() getDisplayName() getMethodDescriptors() getName()

MicroAgentDescriptor.toFor Returns a formatted String representation of — mattedString() this MicroAgentDescriptor object.

MicroAgentDescriptor.toStri Returns the String representation of this — ng() MicroAgentDescriptor object.

TIBCO Hawk Console API Reference MicroAgentDescriptor.MicroAgentDescriptor() | 179

MicroAgentDescriptor.MicroAgentDescriptor() Constructor

Declaration public MicroAgentDescriptor( String name, String displayName, String desc, MethodDescriptor methods[])

Purpose Constructs a MicroAgentDescriptor object.

Remarks All microagents should have unique names. It is recommended that all microagents have a name that is prefaced by their developing organization's Internet domain name. For example, names of microagents developed by TIBCO Software Inc. are prefaced by COM.TIBCO.

Unique microagent names tend to become lengthy. The displayName parameter can be used to provide an abbreviated name which is intended for use for presentation purposes only.

Throws IllegalArgumentException if the parameter conditions are violated.

Parameters Name Description name The name of the microagent. Must be a non-null non-empty string. Should be unique (see Remarks).

displayName A name which may be used as an alternate to name for presentation purposes only.

desc A description of the microagent.

methods An array of MethodDescriptor objects describing the methods supported by this microagent. All methods must have unique names. This array must contain at least one method descriptor. It may not contain null elements.

See Also MethodDescriptor, page 161

TIBCO Hawk Console API Reference 180 | Chapter 9 Talon Package Classes

MicroAgentDescriptor.get...() Accessors Accessors

Declaration public long getChecksum() public String getDescription() public String getDisplayName() public MethodDescriptor[] getMethodDescriptors() public String getName()

Purpose Return information on a microagent’s description and methods.

Remarks The checksum is computed using a CRC-32 algorithm. It takes into account the microagent name and all method names and their signatures. The following attributes of the contained objects are not used to compute checksum as they are not considered part of the microagent's signature:

• MicroAgentDescriptor: display name, description

• MethodDescriptor: description

• TabularDataDescriptor: description

• CompositeDataDescriptor: description

• DataDescriptor: description, default value, legal values, value choices The checksum is not guaranteed to be collision-proof. If two descriptors are the same, they will have the same checksum. If two descriptors have the same name and checksum it is likely, but not guaranteed, that their method signatures match.

Method Name Description Summary getChecksum() Returns the checksum of the microagent's descriptor.

getDescription() Returns a description of the microagent.

getDisplayName() Returns the microagent display name, which may be used as an alternate to name for presentation purposes only. If a display name was not supplied, this method will return the same value as getName().

getMethodDescriptors() Returns the descriptors for the methods supported by this microagent.

getName() Returns the microagent name.

See Also CompositeDataDescriptor, page 148 DataDescriptor, page 151 MethodDescriptor, page 161

TIBCO Hawk Console API Reference MicroAgentDescriptor.get...() Accessors | 181

TabularDataDescriptor, page 190

TIBCO Hawk Console API Reference 182 | Chapter 9 Talon Package Classes

MicroAgentID Class

Package COM.TIBCO.hawk.talon

Declaration public class MicroAgentID extends Object implements Serializable

Purpose MicroAgentID objects are used to identify microagents.

Method Name Description Page Summary MicroAgentID.MicroAgentID() Constructs a MicroAgent object. 183

MicroAgent.getAgent() Returns the Agent object identifying — which agent is hosting the microagent.

MicroAgent.getChecksum() This long returns the checksum of the — microagent's descriptor.

MicroAgent.getDisplayName() This String returns the microagent — display name.

MicroAgent.getInstance() This String returns the microagent — instance.

MicroAgent.getName() This String returns the microagent — name.

MicroAgentID.hashCode() Returns a hash code value for the object. —

MicroAgentID.equals() Determines if two microagent objects — are equal.

MicroAgentID.isService() Returns true if this microagent is a — service. This method is reserved for future use.

MicroAgentID.toString() Returns the String representation of this — MicroAgent object.

See Also TabularDataDescriptor, page 190

TIBCO Hawk Console API Reference MicroAgentID.MicroAgentID() | 183

MicroAgentID.MicroAgentID() Constructor

Declaration public MicroAgentID( String name, String displayName, String instance, long checksum, boolean isService, Agent agent)

Purpose Constructs a MicroAgent object.

Parameters Name Description name The name of the microagent. May not be null or empty string.

displayName A name which may be used as an alternate to name for presentation purposes only.

instance The instance of the microagent. May not be null or empty string.

checksum The checksum of the microagent's descriptor.

isService A flag indicating if this microagent is a service. Reserved for future use.

agent The Agent object identifying the agent hosting this microagent.

See Also Agent, page 144

TIBCO Hawk Console API Reference 184 | Chapter 9 Talon Package Classes

TabularData Class

Package COM.TIBCO.hawk.talon

Declaration public class TabularData extends Object implements Serializable

Purpose This is an open data type used to build tabular data structures.

Remarks TabularData object may have a variable number of rows (including none) and still conform to the TabularDataDescriptor.

Method Name Description Page Summary TabularData.TabularData() Constructs a TabularData object. 185

TabularData.containsRow() Returns true if the specified data elements 186 identify a row in the table.

TabularData.equals() Determines if two TabularData objects 187 are equal.

TabularData.get...() Accessors Return information on the described table. 188 Methods are: getAllData() getAllDataElements() getColumnNames() getColumnTypes() getIndexNames()

TabularData.getRow() Returns the row, uniquely indexed by the 189 indexes parameter, as an array of Objects

TabularData.toString() Returns the String representation of this — TabularData.

See Also OpenData, page 133

TIBCO Hawk Console API Reference TabularData.TabularData() | 185

TabularData.TabularData() Constructor

Declaration public TabularData( String columnNames[], String indexNames[], Object data[][])

Purpose Constructs a TabularData object.

Remarks A TabularData object built to conform to a particular TabularDataDescriptor may have zero (0) rows, but the columnNames parameter must still match those specified by the descriptor.

The data parameter is an array of arrays containing objects representing each cell of the table to be constructed. Every object must be of a type which is one of the open data types as identified by the OpenData interface. Their ordering corresponds directly to their position in the table. Every row must have the same number columns as the length of the columnNames array parameter.

For example: data[x][y] identifies the cell in row x, column y where column y is labeled by columnNames[y]. If data has 0 rows or is null, an empty table is constructed. The values of every cell in a single column must be of the same type or null. Each row must be uniquely indexed. That is, each row must have a unique combination of cell values for those cells in the columns identified by the indexNames parameter.

Parameters Name Description columnNames Identifies the names of all columns. Must contain at least one column name. All column names must be non-null and non-empty strings. No two columns may have the same name.

indexNames Identifies those columns of the table that can be used as a unique index for each row. Must identify at least one index column. All index names must be non-null and non-empty strings. No two array entries may contain the same string. All index names identified by this array must also be present in the array specified by the columnNames parameter.

data An array of arrays containing objects representing each cell of the table to be constructed. Every object must be of a type which is one of the open data types as identified by the OpenData interface. See Remarks for further details.

See Also OpenData, page 133

TIBCO Hawk Console API Reference 186 | Chapter 9 Talon Package Classes

TabularData.containsRow() Method

Declaration public boolean containsRow( DataElement indexes[])

Purpose Returns true if the table contains the row indexed by the specified data elements.

Parameters Name Description

indexes Array of DataElements forming a unique index into the table.

See Also DataElement, page 159

TIBCO Hawk Console API Reference TabularData.equals() | 187

TabularData.equals() Method

Declaration public boolean equals(Object obj)

Purpose Determines if two TabularData objects are equal.

Remarks Two TabularData objects are considered equal if: • They have the same column names (although they may not have been specified in same order). • They have the same index names (although they may not have been specified in same order). • They have the same number of rows (although they may not have been specified in same order). • Each uniquely indexed row of one has the same column values as the same uniquely indexed row of the other.

TIBCO Hawk Console API Reference 188 | Chapter 9 Talon Package Classes

TabularData.get...() Accessors Accessors

Declaration public Object[][] getAllData() public DataElement[][] getAllDataElements() public String[] getColumnNames() public String[] getColumnTypes() public String[] getIndexNames()

Purpose Return information on the described table

Methods . Name Description Summary getAllData() Retrieves all elements of the table in an array of Object arrays, or null if the table is empty.

getAllDataElements() Retrieves all elements of the table in an array of DataElement arrays, or null if the table is empty.

getColumnNames() Returns an array of the column names used to construct this table.

getColumnTypes() Returns an array of strings representing the types of the data objects in each column. The type names in this array correspond to the columns identified in the array returned by getColumnNames() at the same array index. A null element in this array indicates that the column contained only null values and thus the intended type, assuming it wasn't null, could not be determined. A value such as java.lang.String indicates that the column contains values that are either of type java.lang.String or null.

getIndexNames() Returns an array of the index names used to construct this table.

TIBCO Hawk Console API Reference TabularData.getRow() | 189

TabularData.getRow() Method

Declaration public DataElement[] getRow( DataElement indexes[])

Purpose Returns the row, uniquely indexed by the indexes parameter, as an array of Objects, or null if row not found.

Remarks The returned row is represented by an array of DataElement objects, each one corresponding to a cell of the row. DataElement.getName() identifies the column of the cell and DataElement.getValue() returns the value of that cell.

Throws IllegalArgumentException if parameter conditions are violated.

Parameters Name Description

indexes A DataElement array holding the objects used to uniquely identify a row. The DataElement names must all be strings which must be equal, in number and in value, to those returned by getIndexNames(). They identify columns in the table. The corresponding DataElement values represent table cell values (in the corresponding columns) which will be used to retrieve the row. This parameter may not be null.

See Also DataElement, page 159

TIBCO Hawk Console API Reference 190 | Chapter 9 Talon Package Classes

TabularDataDescriptor Class

Package COM.TIBCO.hawk.talon

Declaration public final class TabularDataDescriptor extends CompositeDataDescriptor

Purpose This subclass of DataDescriptor is used to describe objects of type TabularData.

Method Name Description Page Summary TabularDataDescriptor.Tabula Constructs a TabularDataDescriptor 191 rDataDescriptor() object.

TabularDataDescriptor.get...() Return information on the described 192 Accessors parameter. Methods are: getColumnNames() getColumnTypes() getIndexNames()

TabularDataDescriptor.isOpen Returns true if this descriptor describes an 193 Data() open data type.

TabularDataDescriptor.toStrin Returns the String representation of this — g() descriptor. Overrides CompositeDataDescriptor.toString( ).

TIBCO Hawk Console API Reference TabularDataDescriptor.TabularDataDescriptor() | 191

TabularDataDescriptor.TabularDataDescriptor() Constructor

Declaration public TabularDataDescriptor( String name, String desc, DataDescriptor elementDescriptors[] String indexNames[])

Purpose Constructs a TabularDataDescriptor object.

Remarks Note that a type parameter is not required as in DataDescriptor. It is implicitly the TabularData type.

Parameters Name Description name The name of the data parameter being described. It must be a non-null, non-empty alpha numeric string.

desc A description of the parameter being described.

elementDescriptor The array must contain DataDescriptor objects that s describe only open data types. All elements must have unique names. Each descriptor describes a single column in the table, its name is the column's name and its type describes the type of the data the column will hold.

indexNames Identifies those columns of the table that can be used as a unique index for each row. Must identify at least one index column. All index names must be non-null and non-empty strings. No two array entries may contain the same string. All index names identified by this array must have a corresponding DataDescriptor in the array specified by the elementDescriptors parameter.

See Also DataDescriptor, page 151

TIBCO Hawk Console API Reference 192 | Chapter 9 Talon Package Classes

TabularDataDescriptor.get...() Accessors Accessors

Declaration public String[] getColumnNames() public String[] getColumnTypes() public String[] getIndexNames()

Purpose Return information on the described parameter

Method . Name Description Summary getColumnNames() Returns an array of the column names derived from the DataDescriptor elements used to construct this descriptor.

getColumnTypes() Returns an array of column types derived from the DataDescriptor elements used to construct this descriptor. The type names in this array correspond to the columns identified in the array returned by getColumnNames() at the same array index.

getIndexNames() Returns an array of the index names used to construct this table descriptor. They identify which columns can be used to uniquely index each row.

TIBCO Hawk Console API Reference TabularDataDescriptor.isOpenData() | 193

TabularDataDescriptor.isOpenData() Method

Declaration public boolean isOpenData()

Purpose Returns true if this descriptor describes an open data type.

Remarks This overridden method will always return true for this subclass of DataDescriptor because the constructor insures that only the open data type TabularData may be described.

Overrides isOpenData in class CompositeDataDescriptor.

See Also CompositeDataDescriptor.isOpenData(), page 150

TIBCO Hawk Console API Reference 194 | Chapter 9 Talon Package Classes

TIBCO Hawk Console API Reference | 195

Chapter 10 Talon Class Exception Classes

This chapter describes the COM.TIBCO.hawk.console.talon package exception classes and its methods.

Topics

• MicroAgentException, page 196

TIBCO Hawk Console API Reference 196 | Chapter 10 Talon Class Exception Classes

MicroAgentException Class

Package COM.TIBCO.hawk.talon

Declaration public class MicroAgentException extends Exception implements Serializable

Purpose An exception used to signal errors when interacting with microagents.

Remarks This class may be used directly or as a container for other exceptions. When used as a container, the embedded exception is stored in its serialized form. A ClassNotFound exception may be thrown by the getException() method if the class of the contained exception is not available on the receiving JVM.

Method Name Description Page Summary MicroAgentException.Micro Constructs a MicroAgentException. 197 AgentException()

MicroAgentException.getEx Returns the subscription interval of 198 ception() subscriptions constructed for synchronous methods.

TIBCO Hawk Console API Reference MicroAgentException.MicroAgentException() | 197

MicroAgentException.MicroAgentException() Constructor

Declaration public MicroAgentException( String msg)

public MicroAgentException( Exception e) throws IOException

public MicroAgentException( String msg, Exception e) throws IOException

Purpose The first form constructs a MicroAgentException with a detailed message.

The second form constructs a MicroAgentException with an embedded exception and sets the detailed message to be the same as the embedded exception.

The third form constructs a MicroAgentException with an embedded exception and a detailed message.

Remarks Both the second and third forms throw IOException if there is a problem serializing the embedded exception.

Parameters Name Description msg The detailed message.

e The exception to embed.

TIBCO Hawk Console API Reference 198 | Chapter 10 Talon Class Exception Classes

MicroAgentException.getException() Method

Declaration public Exception getException() throws ClassNotFoundException, IOException

Purpose Returns the embedded exception.

Remarks Throws ClassNotFoundException if the class of the embedded exception is not found.

Throws IOException if there is a problem serializing the embedded exception.

TIBCO Hawk Console API Reference | 199

Chapter 11 MicroAgent Plug-in

This chapter explains the MicroAgent and ServiceMicroAgent interfaces.

Topics

• Introduction, page 200 • MicroAgent Plug-in Examples, page 206 • AsyncDataHandler, page 207 • AsyncMethodHandler, page 211 • ContainerEventListener, page 214 • MicroAgent, page 218 • MicroAgentContainer, page 223 • ServiceMicroAgent, page 228 • DynamicMicroAgent, page 230

TIBCO Hawk Console API Reference 200 | Chapter 11 MicroAgent Plug-in

Introduction

The TIBCO Hawk microagent plug-in feature is a Java based API for writing microagents that can reside inside the Hawk agent. It provides all the facilities to write microagents that have synchronous and asynchronous methods. It also provides facilities to add, remove and interact with other microagents that reside within the Hawk agent.

The TIBCO Hawk HMA detects duplicate instances and automatically shuts down the duplicates. This ensures that a given TIBCO Rendezvous session has only one running HMA instance.

The COM.TIBCO.hawk.agent.nest package is used to write TIBCO Hawk microagents that run inside the agent. To run as a microagent in the TIBCO Hawk agent, an object must implement either the MicroAgent, ServiceMicroAgent, or DynamicMicroAgent interface. These interfaces are described below.

MicroAgent Interface

The MicroAgent interface defines methods for obtaining the microagent descriptor and initialization. The descriptor must identify all methods of the microagent that you wish to expose as part of the management interface. Microagent methods can be either synchronous or asynchronous. Exposed synchronous methods must correspond to actual public Java methods in the class. For example, if a descriptor states that there is a synchronous method called getStatus that takes an Integer and returns CompositeData, then there must be a method in the MicroAgent class with the following signature:

public CompositeData getStatus(Integer i) Synchronous methods are invoked using the Java reflection mechanism. Microagents that wish to support asynchronous methods must also implement the AsyncMethodHandler interface. This interface supports subscribing to async methods. The results of invoking an async method are microagent dependant and usually result in an exception, valid data, or empty return. An asynchronous method defined in the descriptor does not require a corresponding public method in the microagent class. The method is optional. If it exists, it must conform to the descriptor (as with synchronous methods) and is used only when the defined asynchronous method is invoked. If it doesn't exist, invoking that asynchronous method results in an empty return.

TIBCO Hawk Console API Reference Introduction | 201

Subscriptions to asynchronous methods are handled by AsyncMethodHandler interface methods, which the microagent must implement if it supports any asynchronous methods. In contrast, subscriptions to synchronous methods are automatically handled by the agent by periodically invoking the corresponding public method.

ServiceMicroAgent Interface

The ServiceMicroAgent interface extends MicroAgent by providing the microagent with access to the MicroAgentContainer through which it can add, remove, and interact with other microagents. In effect, the MicroAgentContainer acts as an interface between the microagent and its hosting agent. It represents the microagent's view of the agent. Microagents that are not ServiceMicroAgents cannot interact with their host agent and thus with other microagents.

In general, a ServiceMicroAgent is only capable of removing those microagents which it itself has previously added.

DynamicMicroAgent Interface

The DynamicMicroAgent interface extends MicroAgent to allow the microagent to handle its own method invocations. The primary differences between a DynamicMicroAgent and a MicroAgent are: • Exposed synchronous methods do not have to correspond to actual public Java methods in the class. • Synchronous methods are not invoked using the Java reflection mechanism. All method invocation requests are passed directly to the DynamicMicroAgent's invokeMethod method. • Asynchronous methods are handled as before except that async method invocations must also be handled by the invokeMethod method.

Running a Microagent in the TIBCO Hawk Agent

A microagent is loaded into the agent by either using the agent's -M command line option or by specifying it in an .hma configuration file. The .hma approach provides greater flexibility. The -M command line approach has been maintained for backwards compatibility with previous releases of the TIBCO Hawk agent.

Using the -M command line option

The -M command line option has the following form:

java COM.TIBCO.hawk.agent.HawkAgent -M -option1 value1 -option2 value2 -option value

TIBCO Hawk Console API Reference 202 | Chapter 11 MicroAgent Plug-in

You can use -file and all other -M options on the same command line before or after this. If what follows the -M option isn't one of the known module types (like AMIService, TIBProtocolAdapter, etc.) then it is treated as a microagent class and the agent attempts to load it.

A microagent loaded via the command line in this manner must have a no-arg constructor, which is used by the agent to create an instance. Once an instance of the microagent has been created, its MicroAgent.initializeMicroAgent(java.lang.String[]) method is called. The argument is a string array that corresponds to the command line arguments supplied to the -M option.

For example, the argument string -M ClassA -opt1 -opt2 a b -M ClassB -opt3 c passed to the agent results in the creation of two microagents, ClassA and ClassB. ClassA will be passed the string array {"-opt1", "-opt2", "a", "b"}. ClassB will be passed the string array {"-opt3", "c"}. The first argument must start with "-". In the previous example, the first argument to ClassA could not be opt1 and must be "-opt1". All microagents loaded in this way are done so before any TIBCO Rendezvous initialization by the agent. The order of the microagents on the command line is significant. They are loaded in the same order as they appear on the command line.

Using an .hma Configuration File

The TIBCO Hawk microagent plug-in directory (hma_plugin_dir) contains .hma configuration files, which specify which microagents to load, and jar files that contain the class files that implement the microagents.

Note that both the -M option and the .hma configuration file allow you to specify a microagent to load and the parameters to pass to it. One difference is that the .hma approach does not require modification to the agent's configuration through the configuration applet or startup script. Another difference is that the .hma approach provides greater flexibility and control over where the class files which implement the microagent reside. At startup, the agent will first process and load any microagents specified using the -M option. It will then search the hma_plugin_dir for configuration files ending with the .hma extension and attempt to load the microagents specified by these files. The prefix of these files is relevant only in determining the order in which their corresponding microagents are loaded, which is in the alphabetical order of the .hma files. Note that multiple .hma files referencing the same microagent will result in multiple microagent instances. Likewise, if a microagent is referenced both by an -M option and an .hma file, the result will be two instances.

TIBCO Hawk Console API Reference Introduction | 203

The hma_plugin_dir is specified to the agent through the -hma_plugin_dir command line option. This option is a member of the "Self" group of agent command line options.

There is one .hma file per microagent. It defines: • The name of the class that implements the microagent. • The list of arguments to be passed to the microagent's COM.TIBCO.hawk.agent.nest.MicroAgent.initializeMicroAgent() method. • A classpath consisting of jar files, which contain the class files that implement the microagent.

The format of the .hma file is formally defined by the DTD:

]>

Example HMA File An example .hma file is shown below.

MyMicroagentClass arg1 arg2 myMicroagent.jar c:\myjars\myUtil.jar classname The element identifies the name of the class implementing the microagent. Example: MyMicroagentClass or com.myfirm.MyMicroagentClass. arguments The element contains zero or more elements which are used as arguments to the method COM.TIBCO.hawk.agent.nest.MicroAgent.initializeMicroAgent().

TIBCO Hawk Console API Reference 204 | Chapter 11 MicroAgent Plug-in

classpath The element must contain one or more elements, which identify the jar files containing the class files that implement the microagent.

path A element must be either a simple jar file name (such as myMicroagent.jar) or a fully qualified file name (such as c:\myjars\myMicroagent.jar). It may not be a relative path name (such as ..\otherjars\myMicroagent.jar). If a element is a simple jar file name, the agent will expect to find it in the hma_plugin_dir. If it is a fully qualified name, the agent will use that file name to find it.

Loading Microagents

The class loader in charge of loading microagents specified in .hma files will first consult an internal class loader before attempting to find a class itself. This internal class loader uses the classpath with which the agent was started. This implies that your microagent code can reference all Java core API classes as well as the classes of the COM.TIBCO.hawk.agent.nest package (required to implement microagents) without including these classes in your elements or jar files.

A microagent loaded as a result of an .hma configuration file can be a ServiceMicroAgent only if all of its elements are simple jar file names and are found in the hma_plugin_dir. ServiceMicroAgents have greater access to the agent so it is desirable to have a greater degree of control over which ServiceMicroAgents are loaded into the agent. Restricting classes that implement them to a single directory provides the administrator with the option to restrict access to this directory using the standard access control mechanisms provided by the operating system.

Recommended Filenaming Convention

The prefix of the .hma file can be anything and only affects the loading order of the microagents because the agent processes .hma files in alphabetical order. However, if order is irrelevant, a useful convention is to give the .hma file the same prefix as the primary jar file containing the microagent's class file(s). Since only one jar file is typically required, deployment of the foo microagent can be accomplished with foo.hma and foo.jar, where foo.hma references foo.jar in its element.

As with the -M option, a microagent loaded in this manner must have a no-arg constructor, which is used by the agent to create an instance.

TIBCO Hawk Console API Reference Introduction | 205

Once an instance of the microagent has been created, its MicroAgent.initializeMicroAgent(java.lang.String[]) method is called. The argument is a string array that corresponds to the elements in the .hma file. Unlike the -M approach, the first argument need not start with a dash ( - ). All microagents loaded in this way are done so before the agent performs any TIBCO Rendezvous initialization.

Interface Summary

Table 2 Interface Description

AsyncDataHandler Used by microagents to service asynchronous method subscriptions.

AsyncMethodHandler A MicroAgent that supports asynchronous methods must implement this interface.

ContainerEventListener Used to register for and receive microagent add or remove events generated by a MicroAgentContainer.

MicroAgent Objects wishing to run as microagents in the TIBCO Hawk agent must implement this interface.

MicroAgentContainer Used to hold active microagents in the agent.

ServiceMicroAgent A MicroAgent that also has access to the MicroAgentContainer.

DynamicMicroAgent A MicroAgent that has its methods invoked through the invokeMethod method.

TIBCO Hawk Console API Reference 206 | Chapter 11 MicroAgent Plug-in

MicroAgent Plug-in Examples

The following set of example Java source files are available in the samples/ma_plugin directory. The examples show the microagent plug-in capability. • DemoMicroAgent.java

This example shows a ServiceMicroAgent that can load and unload other microagents, invoke other microagent methods and listen to MicroAgentContainer events. • DM1.java This example shows the simplest form of microagent. It implements two synchronous methods. • DM2.java This example shows how to support asynchronous methods.

TIBCO Hawk Console API Reference AsyncDataHandler | 207

AsyncDataHandler Interface COM.TIBCO.hawk.agent.nest

Declaration public interface AsyncDataHandler

Description Used by microagents to service asynchronous method subscriptions. An AsyncDataHandler object is passed as an argument to the AsyncMethodHandler.subscribe() method. It is used to handle data and errors resulting from subscriptions to asynchronous methods.

Member Summary Method Description

AsyncDataHandler.onData() Sends data asynchronously when an event occurs.

AsyncDataHandler.onError() Called when an error causes an interruption in the servicing of a subscription.

AsyncDataHandler.onErrorCl Called when there is no longer an error eared() condition which is interrupting a subscription.

TIBCO Hawk Console API Reference 208 | Chapter 11 MicroAgent Plug-in

AsyncDataHandler.onData() Method

Declaration public void onData(java.lang.Object data)

Description Sends data asynchronously when an event occurs.

Parameters

Parameter Description data Data produced by the microagent.

TIBCO Hawk Console API Reference AsyncDataHandler.onError() | 209

AsyncDataHandler.onError() Method

Declaration public void onError(COM.TIBCO.hawk.talon.MicroAgentException e)

Description This method is called when an error causes an interruption in the servicing of a subscription. Once called, this handler will not receive any more data until AsyncDataHandler.onErrorCleared() is called.

Parameters

Parameter Description e An exception identifying the error.

TIBCO Hawk Console API Reference 210 | Chapter 11 MicroAgent Plug-in

AsyncDataHandler.onErrorCleared() Method

Declaration public void onErrorCleared()

Description This method is called when there is no longer an error condition which is interrupting service. It indicates that this subscription can continue to receive data.

TIBCO Hawk Console API Reference AsyncMethodHandler | 211

AsyncMethodHandler Interface COM.TIBCO.hawk.agent.nest

Declaration public interface AsyncMethodHandler A microagent that supports asynchronous methods must implement this interface. The methods of this interface are used to subscribe to asynchronous methods of microagents. A subscription session for a particular MethodSubscription is defined as beginning and ending with the corresponding calls to the startAsyncMethodSubscription() or stopAsyncMethodSubscription() methods with equivalent (defined by MethodSubscription.equals()) MethodSubscription arguments. There can only be one subscription session at a time for each MethodSubscription. In other words, once startAsyncMethodSubscription() is called for a particular MethodSubscription object, it will not be called again until after stopAsyncMethodSubscription() is called for that same MethodSubscription. The microagent is responsible for servicing a subscription for the duration of a subscription session by forwarding data and errors to the AsyncDataHandler supplied in the startAsyncMethodSubscription() method.

Member Summary Member Description

AsyncMethodHandler.startAsy Starts a subscription for an asynchronous ncMethodSubscription() method.

AsyncMethodHandler.stopAsyn Stops a subscription for an asynchronous cMethodSubscription() method.

TIBCO Hawk Console API Reference 212 | Chapter 11 MicroAgent Plug-in

AsyncMethodHandler.startAsyncMethodSubscription() Method

Declaration public void startAsyncMethodSubscription( COM.TIBCO.hawk.talon.MethodSubscription msub, AsyncDataHandler h) throws COM.TIBCO.hawk.talon.MicroAgentException

Description Starts a subscription for an asynchronous method. When invoked, microagents implementing this interface should begin asynchronous delivery of the subscribed-to data through the supplied AsyncDataHandler. This method will be called only once for each unique subscription (defined by the MethodSubscription argument) and may not be invoked again for that same subscription until after the corresponding stopAsyncMethodSubscription() method has been called for this subscription. There are two general types of errors that can occur with method subscriptions: • During the registration of the subscription. This condition should cause this method to throw a MicroAgentException. • During the servicing of the subscription. These errors should be delivered to the onError() method of the supplied AsyncDataHandler. When the error condition clears, the AsyncDataHandler.onErrorCleared() method should be called.

Parameters

Parameter Description msub Identifies what is being subscribed to.

h The object that handles the subscribed to data and errors that occur after successful registration.

Throws COM.TIBCO.hawk.talon.MicroAgentException if an error occurs during the initialization of the subscription.

TIBCO Hawk Console API Reference AsyncMethodHandler.stopAsyncMethodSubscription() | 213

AsyncMethodHandler.stopAsyncMethodSubscription() Method

Declaration public void stopAsyncMethodSubscription( COM.TIBCO.hawk.talon.MethodSubscription msub) throws COM.TIBCO.hawk.talon.MicroAgentException

Description Stops a subscription for an asynchronous method. When invoked, microagents implementing this interface should stop servicing the identified subscription and discard the AsyncDataHandler supplied in the corresponding startAsyncMethodSubscription() call identified by the same MethodSubscription.

Parameters

Parameter Description msub Identifies what is being subscribed to.

Throws COM.TIBCO.hawk.talon.MicroAgentException if an error occurs during the termination of the subscription.

TIBCO Hawk Console API Reference 214 | Chapter 11 MicroAgent Plug-in

ContainerEventListener Interface COM.TIBCO.hawk.agent.nest

Declaration public interface ContainerEventListener

Description ContainerEventListener objects are used to register for and receive microagent add or remove events generated by a MicroAgentContainer.

Member Summary Method Description

ContainerEventListener Called when a listener is first registered with a .onInitial() MicroAgentContainer.

ContainerEventListener Called when a microagent is added to the .onMicroAgentAdded() container.

ContainerEventListener Called when a microagent is removed from the .onMicroAgentRemoved() container.

See Also MicroAgentContainer

TIBCO Hawk Console API Reference ContainerEventListener.onInitial() | 215

ContainerEventListener.onInitial() Method

Declaration public void onInitial(COM.TIBCO.hawk.talon.MicroAgentID[] ids)

Description This method is called when a listener is first registered with a MicroAgentContainer. It receives a list of microagent id's corresponding to all microagents in the container at the time of listener registration. It will always be the first method called in this listener. It will always be called exactly once after listener is registered.

Parameters

Parameter Description ids The array of microagent ids identifying all currently loaded microagents.

TIBCO Hawk Console API Reference 216 | Chapter 11 MicroAgent Plug-in

ContainerEventListener.onMicroAgentAdded() Method

Declaration public void onMicroAgentAdded( COM.TIBCO.hawk.talon.MicroAgentID id)

Description This method is called whenever a microagent is added to the container.

Parameters

Parameter Description id Id of the added microagent

TIBCO Hawk Console API Reference ContainerEventListener.onMicroAgentRemoved() | 217

ContainerEventListener.onMicroAgentRemoved() Method

Declaration public void onMicroAgentRemoved( COM.TIBCO.hawk.talon.MicroAgentID id)

Description This method is called whenever a microagent is removed from the container.

Parameters

Parameter Description id Id of the microagent

TIBCO Hawk Console API Reference 218 | Chapter 11 MicroAgent Plug-in

MicroAgent Interface COM.TIBCO.hawk.agent.nest All known sub-interfaces: ServiceMicroAgent

Declaration public interface MicroAgent

Description Objects wishing to run as microagents in the TIBCO Hawk agent must implement this interface.

Member Summary Method Description

MicroAgent.describeMicr Provides the MicroAgentDescriptor for this oAgent() microagent.

MicroAgent.initializeMi Called by a microagent container before the croAgent() microagent is added to it.

MicroAgent.thisMicroAge Called by a microagent container when this ntAdded() microagent has been successfully added to it.

MicroAgent.thisMicroAge Called when this microagent is removed from ntRemoved() the microagent container.

TIBCO Hawk Console API Reference MicroAgent.initializeMicroAgent() | 219

MicroAgent.initializeMicroAgent() Method

Declaration public void initializeMicroAgent(java.lang.String[] args) throws COM.TIBCO.hawk.talon.MicroAgentException

Description This method is called by a microagent container before the microagent is added to it. It is used to initialize the microagent. A MicroAgentException may be thrown to signal a problem with initialization. If the exception is thrown, the microagent will not be added to the container and no other methods will be called.

Parameters

Parameter Description args The command-line arguments or other initialization parameters that have been designated for this microagent

Throws COM.TIBCO.hawk.talon.MicroAgentException if there is a problem with the initialization.

TIBCO Hawk Console API Reference 220 | Chapter 11 MicroAgent Plug-in

MicroAgent.describeMicroAgent() Method

Declaration public COM.TIBCO.hawk.talon.MicroAgentDescriptor describeMicroAgent() throws COM.TIBCO.hawk.talon.MicroAgentException

Description Provides the MicroAgentDescriptor for this microagent. This method is called after initializeMicroAgent() is called and before the microagent is added to the container.

Throws COM.TIBCO.hawk.talon.MicroAgentException if there is an error generating the description.

TIBCO Hawk Console API Reference MicroAgent.thisMicroAgentAdded() | 221

MicroAgent.thisMicroAgentAdded() Method

Declaration public void thisMicroAgentAdded( COM.TIBCO.hawk.talon.MicroAgentID mid)

Description This method is called by a microagent container when this microagent has been successfully added to it.

Parameters

Parameter Description

mid MicroAgentID that has been assigned to this microagent

TIBCO Hawk Console API Reference 222 | Chapter 11 MicroAgent Plug-in

MicroAgent.thisMicroAgentRemoved() Method

Declaration public void thisMicroAgentRemoved()

Description Called when this microagent is removed from the microagent container. May be used to perform cleanup operations.

TIBCO Hawk Console API Reference MicroAgentContainer | 223

MicroAgentContainer Interface COM.TIBCO.hawk.agent.nest All super-interfaces: COM.TIBCO.hawk.talon.MicroAgentServer

Declaration public interface MicroAgentContainer extends COM.TIBCO.hawk.talon.MicroAgentServer

Description A MicroAgentContainer is used to hold active microagents in the agent. It can be used to add and remove microagents in the TIBCO Hawk agent.

Member Summary

MicroAgentContainer Registers a listener which receives microagent add .addContainerEventL or remove events. istener()

MicroAgentContainer Removes a listener. .removeContainerEve ntListener()

MicroAgentContainer Adds a microagent to the container. .addMicroAgent()

MicroAgentContainer Used to remove a microagent from the container. .removeMicroAgent()

Methods inherited from interface COM.TIBCO.hawk.talon.MicroAgentServer: • describe() • getMicroAgentIDs() • invoke() • subscribe()

TIBCO Hawk Console API Reference 224 | Chapter 11 MicroAgent Plug-in

MicroAgentContainer.addMicroAgent() Method

Declaration public COM.TIBCO.hawk.talon.MicroAgentID addMicroAgent( MicroAgent micro, java.lang.String[] args) throws COM.TIBCO.hawk.talon.MicroAgentException

Description Adds a microagent to the container.

Once this method is called, the microagent's initializeMicroAgent() method is called first. If the microagent is also a ServiceMicroAgent, then its setMicroAgentContainer() method will be called next. This is followed by a call to the describeMicroAgent() method. Finally, once the microagent has been successfully loaded into the container, its thisMicroAgentAdded() method will be called.

Parameters

Parameter Description micro The microagent to add.

args Arguments to be passed to the microagent upon registration.

Throws COM.TIBCO.hawk.talon.MicroAgentException if the microagent could not be added.

TIBCO Hawk Console API Reference MicroAgentContainer.removeMicroAgent() | 225

MicroAgentContainer.removeMicroAgent() Method

Declaration public void removeMicroAgent(MicroAgent micro) throws COM.TIBCO.hawk.talon.MicroAgentException

Description Used to remove a microagent from the container. The microagent's thisMicroAgentRemoved() method will be called after it has been removed.

Parameters

Parameter Description micro The microagent to remove. This must be the same MicroAgent object that was used to add the microagent in the addMicroAgent() method.

Throws COM.TIBCO.hawk.talon.MicroAgentException if the microagent could not be removed.

TIBCO Hawk Console API Reference 226 | Chapter 11 MicroAgent Plug-in

MicroAgentContainer.addContainerEventListener() Method

Declaration public void addContainerEventListener(ContainerEventListener l)

Description Registers a listener which receives microagent add or remove events.

Parameters

Parameter Description l The listener to register.

TIBCO Hawk Console API Reference MicroAgentContainer.removeContainerEventListener() | 227

MicroAgentContainer.removeContainerEventListener() Method

Declaration public void removeContainerEventListener(ContainerEventListener l)

Description Removes a listener.

Parameters

Parameter Description l The listener to remove.

TIBCO Hawk Console API Reference 228 | Chapter 11 MicroAgent Plug-in

ServiceMicroAgent Interface COM.TIBCO.hawk.agent.nest All super-interfaces: MicroAgent

Declaration public interface ServiceMicroAgent extends MicroAgent

Description A ServiceMicroAgent is a MicroAgent that also has access to the MicroAgentContainer. It can thus add, remove, and interact with other microagents.

Member Summary Method Description

ServiceMicroAgent Provides the service microagent with a handle to the .setMicroAgentCon MicroAgentContainer. tainer()

Methods inherited from interface COM.TIBCO.hawk.agent.nest.MicroAgent: • describeMicroAgent() • initializeMicroAgent() • thisMicroAgentAdded() • thisMicroAgentRemoved()

TIBCO Hawk Console API Reference ServiceMicroAgent.setMicroAgentContainer() | 229

ServiceMicroAgent.setMicroAgentContainer() Method

Declaration public void setMicroAgentContainer(MicroAgentContainer c)

Description Provides the service microagent with a handle to the MicroAgentContainer .

Parameter

Parameter Description

c Handle to the MicroAgentContainer.

TIBCO Hawk Console API Reference 230 | Chapter 11 MicroAgent Plug-in

DynamicMicroAgent Interface COM.TIBCO.hawk.agent.nest All super-interfaces: MicroAgent

Declaration public interface DynamicMicroAgent extends MicroAgent

Description A DynamicMicroAgent is a MicroAgent that has its methods invoked through the invokeMethod method instead of through the Java reflection mechanism. Therefore, a DynamicMicroAgent's class does not need to have public methods that correspond to its advertised synchronous methods.

Member Summary Method Description DynamicMicroAgent.invokeMethod() This method handles all method invocations for the microagent.

Methods inherited from interface COM.TIBCO.hawk.agent.nest.MicroAgent: • describeMicroAgent() • initializeMicroAgent() • thisMicroAgentAdded() • thisMicroAgentRemoved()

TIBCO Hawk Console API Reference DynamicMicroAgent.invokeMethod() | 231

DynamicMicroAgent.invokeMethod() Method

Declaration public java.lang.Object invokeMethod(MethodInvocation mi) throws MicroAgentException

Description This method handles all method invocations for the microagent.

Parameter

Parameter Description mi The MethodInvocation object identifying the method name and arguments.

Returns The result of the method invocation.

TIBCO Hawk Console API Reference 232 | Chapter 11 MicroAgent Plug-in

TIBCO Hawk Console API Reference | 233 Index

A AgentMonitor.add...() Methods 89 AgentMonitor.addAgentMonitorListener() 89 addAgentMonitorListener() 89 AgentMonitor.addAlertMonitorListener() 89 addAlertMonitorListener() 89 AgentMonitor.addErrorExceptionListener() 89 addErrorExceptionListener() 89 AgentMonitor.addMicroAgentListMonitorListener() addMicroAgentListMonitorListener() 89 89 addRuleBaseListMonitorListener() 89 AgentMonitor.addRuleBaseListMonitorListener() 89 addWarningExceptionrListener() 89 AgentMonitor.addWarningExceptionrListener() 89 Agent 144 AgentMonitor.initialize() 90 agent AgentMonitor.remove...() Methods 91 loading microagent 201 AgentMonitor.removeAgentMonitorListener() 91 microagents 200 AgentMonitor.removeAlertMonitorListener() 91 Agent.getDns() 144 AgentMonitor.removeErrorExceptionListener() 91 Agent.getHawkDomain() 144 AgentMonitor.removeMicroAgentListMonitorListene Agent.getName() 144 r() 91 Agent.getStartTime() 144 AgentMonitor.removeRuleBaseListMonitorListener() Agent.toString() 144 91 AgentID 64 AgentMonitor.removeWarningExceptionrListener() 9 AgentInstance.get...() Accessors 69 1 AgentInstance.getAgentID() 69 AgentMonitor.shutdown() 92 AgentInstance.getAgentPlatform() 69 AgentMonitorEvent 93 AgentInstance.getAgentVersion() 69 AgentMonitorListener 40 AgentInstance.getCluster() 69 AgentMonitorListener.onAgentAlive() 41 AgentInstance.getIPAddress() 69 AgentMonitorListener.onAgentExpired() 42 AgentInstance.getRuleBaseEngineState() 69 AgentPlatform 94 AgentInstance.getStartTime() 69 AgentPlatform.getOsArch() 94 AgentInstance.getStatusRuleBases() 69 AgentPlatform.getOsName() 94 AgentInstance.getUserData() 69 AgentPlatform.getOsVersion() 94 AgentInstance.isValid() 71 AgentVersion 95, 95 AgentInstance.retransmitAlerts() 72 AgentVersion.getMajorVersion() 95 AgentManager 74 AgentVersion.getMinorVersion() 95 AgentManager.describe() 76 AgentVersion.getUpdateVersion() 95 AgentManager.getMicroAgentIDs() 77 AlertMonitorEvent 96 AgentManager.groupOp() 79 AlertMonitorEvent.get...() Accessors 97 AgentManager.initialize() 80 AlertMonitorEvent.getAlertID() 97 AgentManager.invoke() 81 AlertMonitorEvent.getRuleBaseEngineState() 97 AgentManager.shutdown() 83 AlertMonitorEvent.getTimeGenerated() 97 AgentManager.subscribe() 84 AlertMonitorEvent.RuleBaseEngineStateChanged() 9 AgentMonitor 86 8

TIBCO Hawk Console API Reference 234 | Index

AlertMonitorEvent.RuleBaseStateChanged() 99 DataDescriptor.getType() 152 AlertMonitorListener 43 DataDescriptor.getValueChoices 157 AlertMonitorListener.onAlertMonitorEvent() 44 DataDescriptor.isOpenData() 158 AlertMonitorListener.onRetransmittedAlert() 45 DataDescriptor.toString() 152 AlertState 46 DataElement 159 DataElement.DataElement() 160 DataElement.getName() 159 DataElement.getValue() 159 C DataElement.toString() 159

changes from the previous release xii ClearAlertEvent 100, 100 ClearAlertEvent.getReasonClearedText() 100 E ClearAlertEvent.match() 101 command line ErrorExceptionEvent 102 microagent 202 ErrorExceptionEvent.getConsoleError() 102 CompositeData 145 ErrorExceptionListener 47 CompositeData.CompositeData() 146 ErrorExceptionListener.onErrorExceptionEvent() 48 CompositeData.get...() Accessors 147 examples CompositeData.getDataElements() 147 microagent 206 CompositeData.getValue() 147 ExceptionEvent 103 CompositeData.toString() 145 ExceptionEvent.getConsoleException() 103 CompositeDataDescriptor 148 ExceptionListener 49 CompositeDataDescriptor.CompositeDataDescriptor() 149 CompositeDataDescriptor.getElementDescriptors() 14 8 G CompositeDataDescriptor.isOpenData() 150 CompositeDataDescriptor.toString() 148 getAgentID() 69 ConsoleError 122 getAgentPlatform() 69 ConsoleException 123 getAgentVersion() 69 ConsoleInitializationException 124 getAlertID() 97 ConsoleWarning 125 getAlertIDs() 112 customer support xvii getAlertState() 107 getAlertText() 107 getAllData() 188 getAllDataElements() 188 D getArgumentDescriptors() 165 getChecksum() 112, 180 DataDescriptor 151 getCluster() 69 DataDescriptor.DataDescriptor() 153 getColumnNames() 188, 192 DataDescriptor.getDefault() 155 getColumnTypes() 188, 192 DataDescriptor.getDescription() 151 getDataElements() 147 DataDescriptor.getLegalValueChoices() 156 getDescription() 165, 180 DataDescriptor.getName() 151 getDisplayName() 180

TIBCO Hawk Console API Reference Index | 235 getHandBack() 136 MethodSubscription.toString() 171 getImpact() 165 microagent getIndexNames() 188, 192 examples 206 getIPAddress() 69 load order 202 getMaxResponseTime() 165 loading inside agent 201 getMethodDescriptors() 180 MicroAgent interface 200 getMethodSubscription() 136 microagent, running inside agent 200 getMicroAgentID() 136 MicroAgent.getAgent() 182 getName() 112, 165, 180 MicroAgent.getChecksum() 182 getProperties() 107 MicroAgent.getDisplayName() 182 getReturnDescriptor() 165 MicroAgent.getInstance() 182 getRuleBaseEngineState() 69, 97 MicroAgent.getName() 182 getStartTime() 69 MicroAgentData 176 getState() 112 MicroAgentData.getData() 176 getStatusMicroAgents() 69 MicroAgentData.getSource() 176 getStatusRuleBases() 69 MicroAgentData.MicroAgentData() 177 getTimeGenerated() 97 MicroAgentDescriptor 178 getUserData() 69 MicroAgentDescriptor.get...() Accessors 180 getValue() 147 MicroAgentDescriptor.getChecksum() 180 MicroAgentDescriptor.getDescription() 180 MicroAgentDescriptor.getDisplayName() 180 MicroAgentDescriptor.getMethodDescriptors() 180 M MicroAgentDescriptor.getName() 180 MicroAgentDescriptor.MicroAgentDescriptor() 179 MethodDescriptor 161 MicroAgentDescriptor.toFormattedString() 178 MethodDescriptor.get...() Accessors 165 MicroAgentDescriptor.toString() 178 MethodDescriptor.getArgumentDescriptors() 165 MicroAgentException 196 MethodDescriptor.getDescription() 165 MicroAgentException.getException() 198 MethodDescriptor.getImpact() 165 MicroAgentException.MicroAgentException() 197 MethodDescriptor.getMaxResponseTime() 165 MicroAgentID 182 MethodDescriptor.getName() 165 MicroAgentID.equals() 182 MethodDescriptor.getReturnDescriptor() 165 MicroAgentID.getChecksum() 182 MethodDescriptor.isAsync() 166 MicroAgentID.hashCode() 182 MethodDescriptor.isOpenMethod() 167 MicroAgentID.isService() 182 MethodDescriptor.MethodDescriptor() 163 MicroAgentID.MicroAgentID() 183 MethodDescriptor.toString() 162, 168 MicroAgentID.toString() 182 MethodInvocation 169 MicroAgentListMonitor.getMicroAgentID 104 MethodInvocation.getArguments() 169 MicroAgentListMonitor.getMicroAgentID() 104 MethodInvocation.getMethodName() 169 MicroAgentListMonitor.onMicroAgentAdded() 51 MethodInvocation.MethodInvocation() 170 MicroAgentListMonitor.onMicroAgentRemoved() 52 MethodInvocation.toString() 169 MicroAgentListMonitorEvent 104 MethodSubscription 171 MicroAgentListMonitorListener 50 MethodSubscription.getInterval() 174 MicroAgentListMonitorListener.onMicroAgentAdded MethodSubscription.isAsync() 175 () 51 MethodSubscription.MethodSubscription() 172 MicroAgentListMonitorListener.onMicroAgentRemov

TIBCO Hawk Console API Reference 236 | Index

ed() 52 RuleBaseStatus 111 MicroAgentServer 128 RuleBaseStatus.get...() Accessors 112 MicroAgentServer.describe() 129 RuleBaseStatus.getAlertIDs() 112 MicroAgentServer.getMicroAgentIDs() 130 RuleBaseStatus.getChecksum() 112 MicroAgentServer.invoke() 131 RuleBaseStatus.getName() 112 MicroAgentServer.subscribe() 132 RuleBaseStatus.getState() 112 MonitorEvent 105 MonitorEvent.getAgentInstance() 105 MonitorListener 53 S

ServiceMicroAgent interface 201 O Subscription 134 Subscription.cancel() 135 OpenData 133 Subscription.get...() Accessors 136 Subscription.getHandBack() 136 Subscription.getMethodSubscription() 136 Subscription.getMicroAgentID() 136 P SubscriptionHandler 137 SubscriptionHandler.onData() 138 PostAlertEvent 106 SubscriptionHandler.onError() 139 PostAlertEvent.get...() Accessors 107 SubscriptionHandler.onErrorCleared() 140 PostAlertEvent.getAlertState() 107 SubscriptionHandler.onTermination() 141 PostAlertEvent.getAlertText() 107 support, contacting xvii PostAlertEvent.getProperties() 107 PostAlertEvent.isRetransmittedAlert() 108

T

R TabularData 184 TabularData.containsRow() 186 removeAgentMonitorListener() 91 TabularData.equals() 187 removeAlertMonitorListener() 91 TabularData.get...() Accessors 188 removeErrorExceptionListener() 91 TabularData.getAllData() 188 removeMicroAgentListMonitorListener() 91 TabularData.getAllDataElements() 188 removeRuleBaseListMonitorListener() 91 TabularData.getColumnNames() 188 removeWarningExceptionrListener() 91 TabularData.getColumnTypes() 188 RuleBaseListMonitorEvent 109 TabularData.getIndexNames() 188 RuleBaseListMonitorListener 56 TabularData.getRow() 189 RuleBaseListMonitorListener.onRuleBaseAdded() 57 TabularData.TabularData() 185 RuleBaseListMonitorListener.onRuleBaseRemoved() TabularData.toString() 184 58 TabularDataDescriptor 190 RuleBaseMonitorEvent 110 TabularDataDescriptor.get...() Accessors 192 RuleBaseMonitorEvent.getRuleBaseStatus() 110 TabularDataDescriptor.getColumnNames() 192 RuleBaseMonitorListener 59 TabularDataDescriptor.getColumnTypes() 192

TIBCO Hawk Console API Reference Index | 237

TabularDataDescriptor.getIndexNames() 192 TabularDataDescriptor.isOpenData() 193 TabularDataDescriptor.TabularDataDescriptor() 191 TabularDataDescriptor.toString() 190 technical support xvii TIBCO_HOME xv TIBHawkConsole 113 TIBHawkConsole.getAgentManager() 113 TIBHawkConsole.TIBHawkConsole() 114, 116, 117

W

WarningExceptionEvent 119 WarningExceptionEvent.getConsoleWarning() 119 WarningExceptionListener 60 WarningExceptionListener.onWarningExceptionEvent () 61

TIBCO Hawk Console API Reference