tibco hawk programmer,aos guide · † tibco hawk administrator’s guide this manual includes...

TIBCO Hawk®

Programmer’s GuideSoftware Release 4.9November 2010

Important Information

SOME TIBCO SOFTWARE 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

Figures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ix

Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xi

Preface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xiii

Changes from the Previous Release of this Guide . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .xiv

Related Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xvTIBCO Hawk Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xvOther TIBCO Product Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .xviThird-Party Documentation. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .xvi

Typographical Conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xvii

Connecting with TIBCO Resources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .xixHow to Join TIBCOmmunity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .xixHow to Access All TIBCO Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .xixHow to Contact TIBCO Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .xix

Chapter 1 Introduction to TIBCO Hawk Programming . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1

TIBCO Hawk Requirements. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2

TIBCO Hawk Application Programming Tools and Interfaces . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3AMI Protocol . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3Console API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3Configuration Object API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3AMI Programming Interfaces . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4Security API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4AMI WorkBench . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4Sample AMI Applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4

TIBCO Hawk Programming . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5

Chapter 2 AMI Concepts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .7

Application Management Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8Using a Management Interface. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8

AMI Basics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9Inclusion of Operating Systems Not Supported by TIBCO Hawk Software . . . . . . . . . . . . . . . . . . . . . . . . . . . 9AMI is a Protocol . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9AMI Uses TIBCO Rendezvous Messaging. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10

TIBCO Hawk Programmer’s Guide

iv | Contents

AMI Sessions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10AMI is Part of the TIBCO Hawk System . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11An Instrumented Application Looks like a Microagent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11

TIBCO Rendezvous Concepts Used in AMI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13Daemons and Agents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13Sessions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13Self-Describing Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14Fixed Subject Names for Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14Callback Functions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15Event Managers. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16

AMI Participants . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17Monitoring an Instrumented Application through the TIBCO Hawk Display. . . . . . . . . . . . . . . . . . . . . . . . . . 18Connecting AMI Participants . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18

The AMI Conversation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20First AMI Phase: Discovering the Application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21Second AMI Phase: Describing the Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22Third AMI Phase: Calling the Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23

The AMI Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25Required Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25User-Defined Methods. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25Optional Methods. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25Unsolicited Application Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26AMI and TIBCO Hawk Security . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27

Planning Your Instrumented Application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28

An Example of Planning AMI Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29

Guidelines for AMI Programming . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31

Chapter 3 The AMI Protocol . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33

AMI Initialization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34

Interface Discovery . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35

Method Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36Returned Item Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37An Example of Returning a Table of Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41

Method Invocation. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42Method Invocation of Reserved Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44Method Invocation of Required Reserved Methods. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44Method Invocation of Optional Reserved Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45

Sending an Unsolicited Message . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49

Instrumented Applications and Flavoring . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50


Contents | v

Chapter 4 AMI Message Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .51

Introduction to the Messages. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52

Announcement Message . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53

Discovery Request and Reply Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55

Method Description Request Message . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57

Method Description Reply Message . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58

Method Descriptor Message . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60

Parameter Descriptor List Message. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63

Parameter Descriptor Message . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66

Method Invocation Request Message . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68

Method Invocation Reply Message . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70

Parameter List Message . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72

Returning Results in the Form of Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74

Heartbeat Request and Reply Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75

Repeating Method Invocation Request Message . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77

Stop Repeating Method Invocation Request Message . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79

Start Async Method Invocation Request Message . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81

Stop Async Method Invocation Request Message . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84

Stop Message . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86

Unsolicited Message . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87

Chapter 5 Using the AMI WorkBench. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .89

About the AMI WorkBench. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90AMI WorkBench Window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90Advantages of AMI Workbench . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90

Starting the AMI WorkBench . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91Start AMI WorkBench in Microsoft Windows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91Start AMI WorkBench in UNIX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91

The AMI WorkBench Main Window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92

Invoking Methods. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94

Examining Error Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97

Examining Unsolicited Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98

Chapter 6 Security Framework . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .99

TIBCO Hawk Security Concepts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100Authentication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100Certificates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101


vi | Contents

Authorization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102Data Privacy and Integrity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102Considerations for the TIBCO Hawk System. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102

Implementing a Security Policy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103Creating a Java Security Class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103Framework Protocol . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103Security Objects. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104

HsException . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 105HsException.HsException() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 106

HsIdentifier . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107HsIdentifier.HsIdentifier() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 108

HsOperation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109HsOperation.HsOperation() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 110

HsNode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111HsNode.HsNode() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112HsNode Accessors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113

HsNodeOperation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114HsNodeOperation.HsNodeOperation() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115HsNodeOperation Accessors. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 116

HsGroupOperation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117HsGroupOperation.HsGroupOperation() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 118HsGroupOperation Accessors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 119

HsPackedOperation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 120HsPackedOperation.HsPackedOperation() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121

HsUnpackedOperation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122HsUnpackedOperation.HsUnpackedOperation() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123HsUnpackedOperation Accessors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 124

HsConsoleInterface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125HsConsoleInterface.describe() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 126HsConsoleInterface.initialize() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 127HsConsoleInterface.shutdown(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 128HsConsoleInterface.createId() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 129HsConsoleInterface.pack(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 130

HsAgentInterface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131HsAgentInterface.describe() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132HsAgentInterface.initialize() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 133HsAgentInterface.shutdown(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 134HsAgentInterface.unpack() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 135HsAgentInterface.validateId(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 136

Sample Code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 137


Contents | vii

Chapter 7 AMI Programming Examples. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .141

Sample Directories . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 142

AMI Example In Java . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 143

Appendix A Frequently Asked Questions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .145

Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .149


viii | Contents


Figures | ix

Figures

Figure 1 Monitoring a Remote Application on a Legacy System . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9

Figure 2 Connecting to a Remote Agent Through a Remote Daemon. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19

Figure 3 Connecting to a Remote Agent Through a Local Daemon. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19

Figure 4 Three Stages of AMI Conversation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20

Figure 5 AMI Discovery When the Manager Starts First . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21

Figure 6 AMI Discovery when the Application Starts First . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22

Figure 7 AMI Method Description. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23

Figure 8 AMI Method Invocation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24

Figure 9 Messages Sent During an AMI Conversation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52

Figure 10 Structure of an Announcement Message. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53

Figure 11 Structure of Discovery Request and Reply Messages. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55

Figure 12 Structure of a Method Description Request Message . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57

Figure 13 Structure of a Method Description Reply Message . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58

Figure 14 Structure of a Method Descriptor Message . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60

Figure 15 Structure of a Parameter Descriptor List Message . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64

Figure 16 Structure of a Parameter Descriptor Message. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66

Figure 17 Structure of a Method Invocation Request Message . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68

Figure 18 Structure of a Method Invocation Reply Message . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70

Figure 19 Structure of a Parameter List Message when Used to Send Arguments . . . . . . . . . . . . . . . . . . . . . 72

Figure 20 Structure of a Parameter List Message when Used to Send Results . . . . . . . . . . . . . . . . . . . . . . . 72

Figure 21 Structure of a Heartbeat Request Message. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75

Figure 22 Structure of a Heartbeat Reply Message . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75

Figure 23 Structure of a Repeating Method Invocation Request Message . . . . . . . . . . . . . . . . . . . . . . . . . . . 77

Figure 24 Structure of a Stop Repeating Method Request and Reply Messages . . . . . . . . . . . . . . . . . . . . . . 79

Figure 25 Structure of a Start Async Method Invocation Request Message . . . . . . . . . . . . . . . . . . . . . . . . . . 82

Figure 26 Structure of a Stop Async Method Request Message . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84

Figure 27 Structure of a Stop Message . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86

Figure 28 Structure of an Unsolicited Message . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87


x | Figures

Figure 29 The AMI WorkBench Main Window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92

Figure 30 Result of a Successful Method Invocation That Returns a Table of Data . . . . . . . . . . . . . . . . . . . . 95

Figure 31 Result of a Successful Method Invocation That Returns No Data. . . . . . . . . . . . . . . . . . . . . . . . . . 95

Figure 32 Result of a Failed Method Invocation—Application Returned an Error . . . . . . . . . . . . . . . . . . . . . . 95

Figure 33 Result of a Failed Method Invocation—Discrepancy between Described and Implemented Method . 95

Figure 34 Result of a Failed Method Invocation —Application Did Not Respond and the Invocation Timed Out96

Figure 35 The Error Messages Window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97

Figure 36 The Unsolicited Messages Window. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98

Figure 37 Security Framework Model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104


Tables | xi

Tables

Table 1 General Typographical Conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xvii

Table 2 Common Fields in All Method Invocation Requests. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42

Table 3 Default Arguments for User-Defined Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43

Table 4 Common Fields in All Method Invocation Replies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43

Table 5 Format of Announcement Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53

Table 6 Format of Method Description Request Message . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57

Table 7 Format of Method Description Reply Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59

Table 8 Format of Parameter Descriptor List Message. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65

Table 9 Format of Parameter Descriptor Message . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67

Table 10 Format of Method Invocation Reply Message . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70

Table 11 Format of Parameter List Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73

Table 12 Format of Heartbeat Request Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75

Table 13 Format of Heartbeat Reply Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76

Table 14 Format of Repeating Method Invocation Request Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78

Table 15 Format of Arguments to _startRepeatingMethods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78

Table 16 Format of Arguments to _startAsyncMethods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82

Table 17 Format of Method Invocation Request Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83

Table 18 Format of a Stop Message. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86

Table 19 Format of Unsolicited Message . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87


xii | Tables


| xiii

Preface

This manual describes the TIBCO Hawk® Application Management Interface (AMI) protocol and related Application Programming Interface (API) concepts. This manual describes how AMI can be used to create or modify a program so that it can be monitored by the TIBCO Hawk system. Use of the AMI WorkBench application is also covered.

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 xiv

• Related Documentation, page xv

• Typographical Conventions, page xvii

• Connecting with TIBCO Resources, page xix


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


Preface | xv

Related Documentation

This section lists documentation resources you may find useful.

TIBCO Hawk DocumentationThe 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 C 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.


xvi | 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 DocumentationYou 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 DocumentationYou may find the following third-party documentation useful.

• The Java Language Specification by Gosling, Joy, and Steele


Preface | xvii

Typographical Conventions

The following typographical conventions are used in this manual.

Table 1 General Typographical Conventions

Convention Use

TIBCO_HOME

CONFIG_FOLDER

HAWK_HOME

Many TIBCO products CAN be installed within the same directory. This directory is referenced in documentation as TIBCO_HOME. The value of 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.

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 <TIBCO_HOME>. This directory is 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]


xviii | Typographical Conventions

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 combinations

Key name separated by a plus sign indicate keys pressed simultaneously. For 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.

Table 1 General Typographical Conventions (Cont’d)

Convention Use


Preface | xix

Connecting with TIBCO Resources

How to Join TIBCOmmunityTIBCOmmunity 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 DocumentationAfter you join TIBCOmmunity, you can access the documentation for all supported product versions here:

http://docs.tibco.com/TibcoDoc

How to Contact TIBCO SupportFor 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.


http://www.tibcommunity.com

http://docs.tibco.com/TibcoDoc

http://www.tibco.com/services/support

https://support.tibco.com

xx | Connecting with TIBCO Resources


| 1

Chapter 1 Introduction to TIBCO Hawk Programming

TIBCO Hawk software monitors distributed systems and applications. Applications can be written in C, C++, or Java, or other languages supported by the Application Management Interface (AMI) protocols.

You can interact with TIBCO Hawk applications through the TIBCO Hawk AMI APIs for the appropriate programming languages, through the AMI directly, or through the TIBCO Hawk Console Application Programming Interface (Console API).

Topics

• TIBCO Hawk Requirements, page 2

• TIBCO Hawk Application Programming Tools and Interfaces, page 3

• TIBCO Hawk Programming, page 5


2 | Chapter 1 Introduction to TIBCO Hawk Programming

TIBCO Hawk Requirements

TIBCO Hawk software runs on these operating systems:

• Solaris

• Microsoft Windows (workstation or server)

• HP-UX

• AIX

• Linux

For details on hardware and software requirements, see the TIBCO Hawk Installation and Configuration Guide.


TIBCO Hawk Application Programming Tools and Interfaces | 3

TIBCO Hawk Application Programming Tools and Interfaces

Programming for the TIBCO Hawk system is managed through the Application Management Interface (AMI) protocol, the TIBCO Hawk Console API, or the AMI Application Programming Interface (API) packages.

AMI ProtocolThe TIBCO Hawk Application Management Interface (AMI) is a protocol programmers can use to expose internal application methods to TIBCO Hawk. Such applications are said to be instrumented with an AMI interface. Applications instrumented with AMI are represented by microagents and can be used as a data source by TIBCO Hawk agents. AMI is also used to build adapters and gateways between external applications and the TIBCO Hawk system. AMI uses TIBCO Rendezvous messaging to communicate between an AMI application and TIBCO Hawk agents.

Console APIThe Console API is a comprehensive set of Java interfaces that allow you to manage and interact with TIBCO Hawk agents and monitor alerts generated by these agents. Both the TIBCO Hawk Display and TIBCO Hawk Event Service implement the Console API to monitor and manage agent behavior. Programmers can use the Console API to write custom applications similar to these applications to monitor agent behavior, subscribe to alert messages, and invoke microagent methods.

Configuration Object API The TIBCO Hawk Configuration Object API is a Java language interface for writing custom rulebases. Rulebases are used by TIBCO Hawk agents to monitor and manage systems and applications. The Configuration Object API provides classes to define rules, tests and actions. Instances of these classes are put together to define a new rulebase. For more information, see the TIBCO Hawk Configuration Object API Reference.



AMI Programming InterfacesApplication Management Interfaces (AMI) APIs for C, C++, and Java are provided with the TIBCO Hawk product. The TIBCO Hawk AMI API allows the programmer to create application programs more easily and with fewer errors, as it takes care of all TIBCO Rendezvous and AMI programming details for you.

The TIBCO Hawk AMI API also provides error checking of data formats and method implementations.

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

AMI WorkBenchThe AMI WorkBench is a stand-alone utility that provides a separate graphical user interface for testing an AMI interface or working with AMI applications completely independently of the TIBCO Hawk monitoring system. The AMI WorkBench presents detailed debugging and testing information. Use of the AMI Workbench is discussed in Chapter 5, Using the AMI WorkBench.

Sample AMI ApplicationsSample AMI programs are included with the TIBCO Hawk release. Refer to the TIBCO Hawk Installation and Configuration manual for information on installing the provided sample programs in C, C++, and Java.

The TIBCO Hawk AMI C Programmer’s Reference, TIBCO Hawk AMI C++ Programmer’s Reference, and TIBCO Hawk AMI Java Programmer’s Reference provide additional information on application programming in these languages.


TIBCO Hawk Programming | 5

TIBCO Hawk Programming

In beginning your TIBCO Hawk programming effort, start with this manual, TIBCO Hawk Programmer’s Guide. This manual covers the AMI protocol, AMI messages, the AMI Workbench development tool, and the TIBCO Hawk security framework and its classes.

The TIBCO Hawk system supports API interfaces for C, C++, and Java. These each have a reference manual specific to the API:

• TIBCO Hawk AMI C Programmer’s Reference

• TIBCO Hawk AMI C++ Programmer’s Reference

• TIBCO Hawk AMI Java Programmer’s Reference

These manuals cover the AMI programming interfaces specific to each programming language.

The Console API allows you to directly manage and interact with TIBCO Hawk agents and monitor alerts generated by these agents. It also has a reference manual: TIBCO Hawk Console API Reference. This manual covers the Java-based classes and methods used by the Console functions. By using this API, programmers can write their own custom applications to monitor TIBCO Hawk agent behavior, subscribe to alert messages, and to invoke microagent methods.

The Configuration Object API is a set of Java interfaces that allow you to build custom rulebases. TIBCO Hawk Configuration Object API Reference contains descriptions of each class and method in the Configuration Object API.

The TIBCO Hawk Security API is used to build security plug-in modules used for secure agent and console interactions. It is covered in Chapter 6, Security Framework.

The TIBCO Hawk Application Management Interface (AMI) is a protocol for communication between any application and the TIBCO Hawk system. The TIBCO Hawk AMI allows you to interact with applications that can then be monitored by using TIBCO Hawk tools. While use of the TIBCO Hawk API interfaces is encouraged, the AMI protocol is still supported, for applications where the API interfaces cannot be used or are not desired. Use of the AMI protocol is discussed in Chapter 2, AMI Concepts, and Chapter 3, The AMI Protocol, in this manual. Additionally, Chapter 4, AMI Message Reference, provides explanations of AMI message formats.

The AMI Workbench is a tool designed to help you test and debug your AMI applications. This tool is covered in Chapter 5, Using the AMI WorkBench.


| 7

Chapter 2 AMI Concepts

This chapter explains important concepts needed in building management interfaces using the AMI Protocol.

Topics

• Application Management Interface, page 8

• AMI Basics, page 9

• TIBCO Rendezvous Concepts Used in AMI, page 13

• AMI Participants, page 17

• The AMI Conversation, page 20

• The AMI Methods, page 25

• Planning Your Instrumented Application, page 28

• An Example of Planning AMI Methods, page 29

• Guidelines for AMI Programming, page 31


8 | Chapter 2 AMI Concepts

Application Management Interface

TIBCO Hawk monitoring and Application Management Interface (AMI) applications allow you to manage applications using simple, flexible protocols for interprocess communication.

The TIBCO Hawk AMI provides an open protocol for instrumenting an application with a management interface. An application instrumented in this way can be monitored and controlled by using the tools of the TIBCO Hawk system. This is a TIBCO Rendezvous-based protocol, therefore applications using TIBCO Hawk AMI can exploit the scalability and reliability of TIBCO Rendezvous.

Applications using the AMI protocol are said to be ’instrumented with an application interface. The application can thus be monitored and controlled by means of TIBCO Hawk tools. Writing an AMI wrapper to interface with an API or other application allows management of third-party applications by means of the TIBCO Hawk software.

You can implement the AMI portion of your application in C, C++ or Java. and manipulate it through the AMI Workbench. More information on using the API interfaces provided for these languages, refer to TIBCO Hawk AMI C Programmer’s Reference, TIBCO Hawk AMI API C++ Programmer’s Reference, and TIBCO Hawk AMI Java Programmer’s Reference

Using a Management InterfaceComplex distributed systems require network, systems, and application management. The TIBCO Hawk Application Management Interface and related TIBCO Hawk applications provide an integrated solution for managing large-scale distributed systems.

The TIBCO Hawk software examines processes, log files, and output by using command-line executable processes to manage distributed applications. These applications are said to be managed ’from the outside.’ Instrumenting an application with AMI allows you to use methods to retrieve information and change internal states, thus also allowing management ’from the inside’. TIBCO Rendezvous messaging, TIBCO Hawk monitoring, and the TIBCO Hawk Application Management Interface provide application management using a simple, flexible protocol. This protocol uses inter-process communication built on the TIBCO Rendezvous foundation and the tools of the TIBCO Hawk monitoring solution.


AMI Basics | 9

AMI Basics

This section presents a brief overview of the TIBCO Hawk Application Management Interface (AMI).

Inclusion of Operating Systems Not Supported by TIBCO Hawk SoftwareManagement interfaces can be built in any programming language and on any operating system supported by TIBCO Rendezvous software.

Applications instrumented with an AMI interface can communicate with a remote TIBCO Rendezvous daemon, which means that a TIBCO Hawk agent can monitor the application from another computer. In this way, TIBCO Hawk software can be used to manage the application even if TIBCO Hawk software does not support the operating system on which the software is used. For example, you can monitor legacy systems by having applications (or AMI wrappers around them) communicate with remote agents on other platforms, as in Figure 1.

Figure 1 Monitoring a Remote Application on a Legacy System

AMI is a ProtocolThe TIBCO Hawk Application Management Interface (AMI) is a messaging protocol, a formal specification that defines the procedures applications should follow when sending and receiving data.

legacy systemwith no agent

computer withagent

TIBdaemon

agent

daemon

AMIApp

this is theagent's primarylocal monitoring

session

this is the remotesession of the AMIapp running on the

legacy system



Creating a minimally functional management interface using AMI is relatively simple, since only two types of message exchanges (methods) are required. This makes AMI simple to learn and implement.

An application that uses the AMI protocol is said to be instrumented with an application interface. Such an application is known as an instrumented application or a managed application. The application interface is the part of the program that implements the AMI protocol.

TIBCO Hawk AMI provides language-specific APIs for the C, C++, and Java programming languages. These APIs are described in the following manuals:

• TIBCO Hawk AMI API C Programmer’s Reference,

• TIBCO Hawk AMI API C++ Programmer’s Reference, and

• TIBCO Hawk AMI API Java Programmer’s Guide.

AMI Uses TIBCO Rendezvous MessagingAMI relies on standard TIBCO Rendezvous reliable message transmission. An application instrumented with AMI usually communicates with autonomous TIBCO Hawk monitoring agents. Such an application makes certain data and methods visible to a TIBCO Hawk agent through the AMI interface. The agent calls these methods using a TIBCO Rendezvous callback function to retrieve data and/or make changes within the application.

Instrumenting an application with AMI makes use of TIBCO Rendezvous features such as inboxes, message formats, and data types. Review the book TIBCO Rendezvous Concepts as well as the TIBCO Rendezvous and TIBCO Hawk manuals for your specific programming language before beginning to work with AMI.

AMI SessionsAn AMI session allows you to interface a managed application with its manager.

Managed Applications and Managers

Two entities participate in an AMI conversation:

• A managed application is an application instrumented with an AMI interface.

• A manager is any process that monitors and/or controls such an application.

Between the application and the manager lies the management interface, which is the part of the application that implements the AMI protocol.


AMI Basics | 11

Stages of AMI

The AMI system works in three stages: 1. A mutual discovery stage, in which the manager and application connect.

2. A stage of application method description, in which the application describes to the manager the methods it wants to make visible.

3. A stage of application method invocation, in which the manager calls application methods to retrieve data or make changes.

These stages are further described in the section The AMI Conversation, page 20

AMI is Part of the TIBCO Hawk SystemThe TIBCO Hawk Enterprise Monitor is a system based on distributed agents that perform applications and systems management. Each TIBCO Hawk agent collects systems and applications statistics for autonomous monitoring on a single computer. Agents collect data using objects called microagents, each of which typically represents one monitored resource.

Agents are configured using rulebases, collections of monitoring rules. Rules designate under what conditions alerts should be generated and what corrective actions should be taken.

The TIBCO Hawk Display program is used to:

• Examine alert states of all agents on the network.

• Review alert messages.

• Interact with agents and their microagents.

• Create and distribute rulebases.

When an application is instrumented with an AMI interface, it assumes the role of a microagent in the TIBCO Hawk system. A TIBCO Hawk agent acts in the role of an AMI manager.

An Instrumented Application Looks like a MicroagentYou typically interact with a TIBCO Hawk agent by calling the methods of microagents associated with that agent. An AMI-instrumented application appears and acts as though it were a microagent in the TIBCO Hawk system.

Interaction with an AMI-instrumented application can use the following means:

• Interactive monitoring using the TIBCO Hawk Display.

An example of this might be using the TIBCO Hawk Display to survey many instances of an application by means of a network query. Another example



might be to make simultaneous changes to many instances by performing a network action.

• Automating monitoring and management of the application by creating rulebases to be processed by TIBCO Hawk agents.

An example might be creating rulebases to monitor the application’s error state, detect dangerous conditions, and increase the output of debug information until the problem is resolved.


TIBCO Rendezvous Concepts Used in AMI | 13

TIBCO Rendezvous Concepts Used in AMI

This section provides a brief overview of some TIBCO Rendezvous concepts used in instrumenting an application with AMI. Review the book TIBCO Rendezvous Concepts before beginning AMI coding.

Daemons and AgentsTIBCO Rendezvous messages are distributed by TIBCO Rendezvous daemons. A TIBCO Rendezvous daemon is a process responsible for managing all message traffic among the entities to which it is connected. Typically, one daemon manages traffic on one computer, although remote applications can also be included in a daemon’s scope.

TIBCO Hawk monitoring takes place through the actions of distributed agents. An agent is a process responsible for monitoring systems and applications on a single computer. Typically, one agent communicates with one local daemon, although agents and daemons can also communicate remotely.

Normally, an application instrumented with AMI will interact with one daemon and one agent on its local computer. This is the most simple method. An application can, however, interact with a remote daemon and a remote agent, if necessary. This could be necessary if the application is running on an operating system on which TIBCO Hawk agents are not supported.

SessionsA session is a single connection from an application to a TIBCO Rendezvous daemon. TIBCO Rendezvous software assures sessions stay connected by restarting the appropriate TIBCO Rendezvous daemon and reopening connections, if necessary.

An application using the TIBCO Rendezvous system to communicate with other applications always creates a TIBCO Rendezvous session and uses this session to create senders (that send messages about subjects) and listeners (that subscribe to subjects). These can be objects, when the application is written in an object-oriented language, or they can be handles. For example, in Java, a sender is an object, but in C the sender is a handle that is passed as an argument to a group of related functions.



Self-Describing MessagesAll TIBCO Rendezvous messages are self-describing, meaning that they carry enough information that a receiving application can read their data with no knowledge of the sending application. Messages achieve this by bundling a name and data type with each data item.

The AMI protocol uses a subset of standard TIBCO Rendezvous message types, listed below:• TIBRVMSG_I32

• TIBRVMSG_F64

• TIBRVMSG_STRING

• TIBRVMSG_BOOL

• TIBRVMSG_MSG (a nested message)

Any TIBCO Rendezvous message can include any number of other messages; messages can be nested to any number of levels. Nested TIBCO Rendezvous messages, also called composite messages, are used extensively in the AMI protocol.

TIBCO Rendezvous messages are published with subject names, which are human-readable identifiers such as COM.MYCOMPANY.MYAPP. Subject names consist of some number of elements separated by periods. For example, the subject name COM.MYCOMPANY.MYAPP has three elements. An example familiar to users of the TIBCO Hawk system would be COM.TIBCO.Hawk.SysInfo .

TIBCO Rendezvous messages are often used for broadcast, multicast, and point-to-point messaging. However, all TIBCO Rendezvous messages used in AMI stay local to a single TIBCO Rendezvous daemon and are not sent over the network to other daemons. This makes AMI a very scalable solution for large-scale application monitoring, since all communication between the managed application and the TIBCO Hawk agent stays local to the computer on which both are running. The only time AMI-related messages involve network traffic is when the agent or application connects to a remote daemon (as described in Connecting AMI Participants on page 18). In this case, however, all such traffic is point-to-point.

Fixed Subject Names for MessagesAn AMI interface uses fixed subject names, as follows:

• _LOCAL._HAWK.AMI.START: A message with this subject name announces the arrival of an application’s AMI interface. The application typically sends a message with this subject name only when the application starts.


TIBCO Rendezvous Concepts Used in AMI | 15

• _LOCAL._HAWK.AMI.DISCOVERY: A message with this subject name is sent by managers wishing to discover what AMI applications are running. Managers typically send a message with this subject name only when they start.

• _LOCAL._HAWK.AMI.INFO : A message with this subject name is sent by a managed application when it wants to send unsolicited information to its manager.

• _INBOX.<xyz>: An inbox address is a special subject name generated at runtime by a TIBCO Rendezvous session. An inbox address (also called an inbox name) creates a globally unique endpoint for point-to-point communication. An application instrumented with AMI should not change inbox addresses, but should use them exactly as they are specified by the TIBCO Rendezvous session.

• _LOCAL._HAWK.AMI.STOP : A message with this subject name is send by the application before it exits.

Callback FunctionsA callback function is a hook into an application, through which the TIBCO Rendezvous daemon delivers new messages. When you initiate a subscription to a subject name, you furnish to the TIBCO Rendezvous daemon the address of the callback function it should call to deliver messages. When the daemon receives a message in which you have declared a subscription interest, it invokes your callback function.

The argument to the callback function is the composite message the daemon received. Other than verifying that the message has the proper structure, the daemon does nothing except pass it on. You are expected to know how to interpret the data inside the message, based on the names and types given to each element of the message.

Messages sent during AMI interactions have fixed structures, and their structures are part of the AMI protocol. Nested within these AMI messages, you include other messages unique to your application. Part of the interaction involved in AMI is in describing the structure of these unique messages to a manager.

The callback function should not block and should return control to the application fairly quickly. See the section of TIBCO Rendezvous Concepts on callback functions for more information on writing non-blocking callbacks.

Note: These subject names all start with an underscore ("_"). Any subject names with this prefix are reserved for use by the TIBCO Rendezvous and TIBCO Hawk systems and must not be used by your applications for other purposes.



Event ManagersIf you are used to programming in event-driven windowing environments, you are probably already familiar with event managers. Every application that uses TIBCO Rendezvous messaging must use an event manager to handle incoming messages. The types of event managers used in some languages supported by TIBCO Rendezvous software are as follows:

• C programs typically use the TIBCO Rendezvous event manager.

• C++ programs can use either the TIBCO Rendezvous event manager or one provided by the API with which they are working.

• In Java and ActiveX, TIBCO Rendezvous software implicitly uses the standard event dispatch mechanism. No explicit call is needed to begin dispatching inbound messages or timer events.


AMI Participants | 17

AMI Participants

The AMI interface connects two entities: a managed application and a manager.

A manager is a process that communicates with a managed application, retrieving data from it and controlling it. Typically a manager will be one of two programs:

• A TIBCO Hawk Agent

• The AMI Workbench

The TIBCO Hawk Display is not a possible manager because TIBCO Hawk agents are the active monitors in the TIBCO Hawk system. The TIBCO Hawk Display is merely a window through which to interact with agents.

A managed application is an application instrumented with an AMI interface (also called an instrumented application). The managed application can be the application you intend to monitor and control, or it could be another application acting as a wrapper around the first application.

A management interface is the part of the application that is responsible for communications with the manager, as defined by the AMI protocol.

An instrumented application can interact with multiple managers, although typically it interacts with only a single manager. An application can also implement multiple management interfaces, in which case it appears to a manager as multiple manageable objects.

A management interface can be divided into two major portions:

• The initialization code. This code creates a TIBCO Rendezvous session, passes on the address of a callback function through which messages are to be received, and sets up the functionality to negotiate discovery with a manager.

In an object-oriented language, initialization code creates objects that will handle interactions: an AMI interface object, a TIBCO Rendezvous session object, and sender and listener objects to send or receive messages associated with AMI subject names.

In a non-object-oriented language, initialization code carries out these tasks by calling methods of the TIBCO Rendezvous API for the language in which the AMI interface is implemented.

Note: An instrumented application is not dependent on the presence of an AMI manager. The relationship between manager and managed application is completely voluntary. The management interface might be active only in some instances of the application, or only at specific times during an instance’s activity.



• A callback function that receives messages from the session. The callback function examines the message and typically passes it on to one of several internal methods for processing.

Monitoring an Instrumented Application through the TIBCO Hawk DisplayA microagent is an object used by a TIBCO Hawk agent to carry out certain related tasks: to run scripts, to obtain file system information such as free hard disk space or to retrieve a process table. In the TIBCO Hawk Display or AMI Workbench, instrumented applications appear in the list of microagents, using the name that the application provides through its AMI interface. Any methods thus made visible appear as if they are microagent methods, with arguments and results as described.

Interaction with an instrumented application can occur in the following ways:

• Using the AMI Workbench, you can interact with a single instance of an application, either from the computer where it is located or from another computer connecting remotely. You can retrieve information from it or make changes to it.

• Using the TIBCO Hawk Display, you can interact with an instance of your application from any location in the network.

• Using the TIBCO Hawk Display, you can set up subscriptions to data that your methods provide and use tables and charts to view the results over time.

• Using the TIBCO Hawk Display, you can interact with all instances of your application, across a network, by using network query and network action.

• Using the TIBCO Hawk Display and the rulebase editor, you can create rules to automate monitoring your application from anywhere in the network. Normally, you will create a special rulebase for a managed application and load it onto all TIBCO Hawk agents on computers where that application resides.

Connecting AMI ParticipantsAn instrumented application should use a similar TIBCO Rendezvous configuration to the one being used by its manager.

• If you are using the AMI Workbench as your manager, start the AMI Workbench with the same service , network, and daemon options as you are using for the TIBCO Rendezvous session set up in your application.

• If you are using a TIBCO Hawk agent as your manager, start the TIBCO Hawk agent with the same service , network, and daemon options for its primary monitoring session as for the TIBCO Rendezvous session set up in the


AMI Participants | 19

application. You can also configure the agent to use additional TIBCO Rendezvous sessions to monitor AMI activity. See the TIBCO Hawk Installation and Configuration for details on configuring agents to use additional AMI sessions.

If you want to monitor an application running on a host without a TIBCO Hawk agent, you have two options:

• Establish a session from your application to a remote TIBCO Rendezvous daemon that services a TIBCO Hawk agent on another computer, as in Figure 2.

Figure 2 Connecting to a Remote Agent Through a Remote Daemon

• Have a TIBCO Hawk agent on another computer establish a remote connection to the TIBCO Rendezvous daemon on the computer on which your application is running, as in Figure 3.

Figure 3 Connecting to a Remote Agent Through a Local Daemon

computer withno agent

computer withagent

TIBdaemon

agent

daemon

App


session

this is theapp's remote

session

this is the agent'ssecondary

remote AMImonitoring

session

computer withno agent

computer withagent

TIBdaemon

agent

daemon

App


session

this is theapp's local

session



The AMI Conversation

This section describes in detail the three phases involved in communication between an instrumented application and its manager. The three phases of the AMI conversation are:

• discovery

• method description

• method invocation

Figure 4 illustrates the three phases of an AMI conversation.

Figure 4 Three Stages of AMI Conversation

Managed A

pplication

Man

ager

Phase 1: Discovery(one scenario:

application starts first)

Phase 2: Method Description

Phase 3: Method Invocation

Send discoveryrequest

Send methoddescription request

Request methodinvocation

Reply todiscovery request

Reply to methoddescriptionrequest

Reply to methodinvocation

Tim

e






The AMI Conversation | 21

First AMI Phase: Discovering the ApplicationDiscovery between the application and manager can happen in one of two ways, depending on which entity starts first.

If the Manager Starts First

If the manager starts before the application, the interaction is as shown in Figure 5.

Figure 5 AMI Discovery When the Manager Starts Firstt

The steps involved are:

• When the manager starts, it sends a message with the subject _LOCAL._HAWK.AMI.DISCOVERY. The manager typically does this only once, at startup. If no instrumented applications are active, the message is not heard.

• The manager also registers its interest in (subscribes to) the subject name _LOCAL._HAWK.AMI.START, telling it to detect any managed applications when they start up.

• When the application starts, it sends a local message with the subject _LOCAL._HAWK.AMI.START. This message includes information which describes the application to the manager (its name, inbox address, AMI version, and help string).

Because the subject names of these messages start with the element _LOCAL , they are only received by applications connected to the same daemon. In most cases, this means that all recipients are located on the same computer and the announcement message does not affect the network.

If the Application Starts First

If the application starts before the manager, the interaction is as shown in Figure 6.

Ap

plica

tion

Man

ager

Manager starts first

Receiveannouncement

Sendannouncement

Tim

e




Figure 6 AMI Discovery when the Application Starts First

The steps involved are:

• When the application starts, it sends a local message with the subject _LOCAL._HAWK.AMI.START. If no managers are available, the message is not heard.

• The application also registers its interest in the subject name _LOCAL._HAWK.AMI.DISCOVERY so that it can reply to any managers that start.

• When a manager starts, it sends a message with n the subject _LOCAL._HAWK.AMI.DISCOVERY. This message includes only the name of the manager, which the managed application usually ignores, unless it is to log this information. The manager typically performs this operation only once, at startup. This message is only sent to local recipients.

• The application replies to the discovery message with a message identical to the announcement message sent earlier.

At the end of the discovery phase, the manager and the application have established a connection that allows them to communicate through the inbox address. However, the manager is not yet aware of any details of the application’s interface.

Second AMI Phase: Describing the MethodsAfter the manager and application have exchanged announcement or discovery messages, the manager then sends a message asking the application to describe its methods. The method name specified in this message is _describeMethods . Every instrumented application must implement this method.

Ap

plication

Ma

nage

r

Application starts first



Tim

e

Sendannouncement


The AMI Conversation | 23

In the _describeMethods method, the application returns a message to the manager containing a list of methods and their descriptions. This method makes applications that use AMI self-describing, because they spell out everything to be made visible. Thus, the manager has all it needs for when it actually calls the methods.

Figure 7 AMI Method Description

The message sent to the manager in _describeMethods has nested inside it a series of messages that describe each method. These are known as method descriptor messages. Each method descriptor message has messages nested inside it, which describe the types of arguments and types of returns applicable to each method. This is illustrated in Figure 7. From this description, the manager determines what structure of message to send when invoking the method, as well as how to interpret the message the application sends back.

At the end of the method description phase, the manager is aware of all message exchanges supported by the application and is ready to begin sending messages of the specified types.

Third AMI Phase: Calling the MethodsAfter the application has been discovered and the methods have been described, the real work takes place. Acting either on cues from a human user or by processing the rules in a rulebase, the manager sends messages to the application invoking the described methods and awaits its reply. The method invocation messages sent by the manager conform to descriptions given by the application in _describeMethods as to which arguments are appropriate for each method.

The application sends back a message whose contents conform to the structure the application described to the manager in _describeMethods .

Note: While the interface is said to describe the application’s methods, what it is really doing is describing the TIBCO Rendezvous messages it understands and will respond to. The _describeMethods method describes acceptable message exchange

ApplicationM

anag

er Reply to methoddescription request

Tim

e

Send methoddescription

request

Method description

Parameter description

Parameter description



When the manager receives the response to its method call, it presents the returned information to the human user. This scenario repeats itself over and over again until the session is terminated by either the application or the manager.

Figure 8 AMI Method Invocation

The manager also periodically sends a message to the application referring to the _heartbeat method. The application replies by sending back a message containing only a CONTEXT field. If the application does not respond, the manager registers the application as no longer available. After the discovery process is complete, the manager uses this mechanism to monitor the status of managed applications.

ApplicationM

anag

erReply to methodinvocation request

Tim

e

Send methodinvocation request

Results

Arguments

moremore


The AMI Methods | 25

The AMI Methods

An AMI interface may include three types of methods:

• Required methods, which every instrumented application must have.

• User-defined methods, which carry out the tasks you make visible.

• Optional methods, which you may implement to provide optional functionality.

Required MethodsOnly two methods are required by the AMI protocol.

• The _describeMethods method describes to the manager the message structures your application wants to exchange. This method takes no arguments and returns a nested message describing all the methods that the application supports, each with its arguments and results.

• The _heartbeat method responds to a heartbeat request message from a manager.

These two methods are assumed to be available in all management interfaces. Thus, they need not be described to the manager when describing other methods.

User-Defined MethodsUser-defined methods are all the methods whose message structures are advertised in the _describeMethods message, except for optional methods. User-defined methods are for application monitoring and control. With autonomous monitoring, the manager typically invokes one of these methods at some specified interval. This effectively results in a periodic polling of the interface to obtain data.

Optional MethodsOne of the most common tasks the TIBCO Hawk system carries out on an instrumented application is retrieving information on a regular interval. (In the TIBCO Hawk Display you specify this interval as a data delivery interval for a rule’s data source.)

Note: User-defined methods must not use the prefix "_". This prefix is reserved for required and optional methods.



Normally, a manager will repeatedly send a message to the managed application on this interval to retrieve the information. To make periodic data gathering more efficient, your application can take over this task by saving the message, counting time using its own timer, and sending out answers on a regular interval. Implement the optional method _startRepeatingMethod and describe this to the manager in your response to the _describeMethods method call.

When the manager comes across a method that is to be called repeatedly, it will bundle the method-calling message inside a second repeat-instruction message that contains the message for the method call, the collection interval, and the number of times to respond. Your application should start its own timer and call the specified method at intervals until the requested number of messages has been sent.

To further improve efficiency, you can optionally support the method _stopRepeatingMethod , which the manager will call if it wants you to stop your repeated response before the specified number of replies has been sent. It is not mandatory to implement this method even if you have implemented _startRepeatingMethod , because the sequence should always expire on its own.

Additionally, the _startAsyncMethod method may be used by the manager to subscribe to data provided by a specified asynchronous user defined method. This optional method has to be described to the manager in your response to the _describeMethods method call. You can support the _stopAsyncMethod , which the manager uses to stop the asynchronous method subscription. It is not mandatory to implement this method even if you have implemented _startAsyncMethod , because the sequence should always expire on its own.

Unsolicited Application MessagesAn application can send unsolicited messages to any local manager listening on the subject _LOCAL._HAWK.AMI.INFO . This can include a TIBCO Hawk agent. You can create a rulebase to specifically detect these messages. There are three main reasons to send unsolicited messages:

• To transmit asynchronous data. The TIBCO Hawk agent can periodically retrieve information from applications instrumented with AMI, as it does with microagents. There can be times, however, when you want to monitor events as they happen. An unsolicited message of this kind would have the type INFO .

• To send a warning. Sending an unsolicited warning to the manager is useful when you are monitoring a situation that rarely occurs. An unsolicited message of this kind would have the type WARNING .

• To flag an error. Exception-handling code is probably already being used in your application to deal with unforeseen circumstances and latent bugs. A


The AMI Methods | 27

central exception-handling method is the perfect place to send a message to the manager, describing the problem. You can also provide crucial state information that can be used to debug the problem. An unsolicited message of this kind would have the type ERROR .

Sending an unsolicited message does not automatically imply that a TIBCO Hawk agent will process it and send a corresponding alert to the TIBCO Hawk Display. Instead, the agent must have loaded a rulebase that instructs it as to how to handle these messages. A rule that monitors unsolicited messages uses the TIBCO Hawk method _onUnsolicitedMessage as its data source. Tests in such a rule can search for specific strings in the TEXT field of unsolicited messages. For example, a test might become true if an unsolicited message contains the string MyApp.dataloss .

There are two reasons the TIBCO Hawk agent does not automatically send an unsolicited message to the TIBCO Hawk Display:

• It gives you the ability to take action only on those messages you deem necessary at the time. When building a management interface, it is often difficult to know which messages will be important at a later time. Sending unsolicited messages in your central exception-handling code is recommended. By testing for text strings or message ID numbers, you can change your monitoring strategy without recompiling your application. For example, you might create different rulebases to monitor and respond to different unsolicited messages. Choosing a monitoring strategy can then be merely a matter of loading or unloading these rulebases.

• Using the TIBCO Hawk agent as a unsolicited-message filter provides a level of protection against applications that mistakenly misuse this facility. Examples might be applications that generating too many messages or get caught in a loop.

AMI and TIBCO Hawk SecurityTIBCO Hawk software includes a security framework that can be customized to restrict access to the TIBCO Hawk agent and its microagents. Access can be granted or denied based on virtually any criterion. Because managed applications appear to the TIBCO Hawk agent as microagents, this mechanism is inherently extended to messages sent to applications instrumented with AMI. For more information on implementing a security policy, see Chapter 6, Security Framework, on page 99.



Planning Your Instrumented Application

These steps can help you in planning your AMI interface:

1. Review Chapter 3, The AMI Protocol to determine the requirements for creating an interface. Examine the samples of AMI code included with the TIBCO Hawk distribution to see how these requirements are carried out in code.

2. Copy one of the AMI code samples and amend it to add one or two methods, testing the interface with the AMI Workbench. Become familiar with TIBCO Rendezvous message structures and AMI requirements before you start creating a more complex interface.

3. When you are ready to create an interface to your application, consider what data and methods is to be accessed or changed through the application’s management interface:

— List the separate data items you want to be able to retrieve.

— List the data items you want to be able to change.

— List the actions you want to be able to carry out.

Each of these items will become a supported method of your AMI interface.

4. For each of these methods, decide what arguments it will use and what results it will return. If a method uses arguments, consider what course to take if a default argument is supplied.

5. Using the collected information for each method, create an outline detailing the message structure to be returned to describe these methods to a manager. Specify which TIBCO Rendezvous message types to use.

6. Use this outline to write a _describeMethods method, which returns a nested message. Refer to Chapter 3, The AMI Protocol, and the Chapter 4, AMI Message Reference, on page 51 to work out the message structures to describe.

7. Set up the code to initialize the TIBCO Rendezvous session.

8. Write methods that respond to method invocation messages from the manager. In creating each message, use an outline as you did with the _describeMethods message, to lay out what information the message will include.


An Example of Planning AMI Methods | 29

An Example of Planning AMI Methods

Let us suppose you have a transaction-processing application that needs to be monitored so that its message queue length doesn't grow too large. Instances of this application might make up a fault-tolerant group with primary/secondary status, which you want to autonomously monitor but also to interactively control.

Defining these needs, you could list two items:

• The manager should retrieve the application’s queue length on a periodic basis.

• The manager should retrieve the application’s primary/secondary status on a periodic basis.

You now create these methods:

• getQueueLength, which takes no arguments and returns the queue length.

• getFTStatus , which takes no arguments and returns the fault-tolerant status (primary or secondary) of the application.

• makePrimary, which takes no arguments and sets the fault-tolerant status of the application instance to primary.

• makeSecondary, which takes no arguments and sets the fault-tolerant status of the application instance to secondary.

Since you will be using a TIBCO Hawk agent as the manager, you build a rulebase with two rules, as follows:

• The first rule has as its data source the getQueueLength method. It raises an alert if the queue length is greater than 200.

• The second rule has as its data source the getFTStatus method. It sends a notification each time there is a fault-tolerant state transition.

From the TIBCO Hawk Display, operators can control the fault-tolerant state of any instance of the application by invoking the makePrimary or makeSecondary methods.

Other possible AMI examples might include:

• Methods to dynamically control trace or debug levels.

• Methods to drop or re-request information from data streams.

• Methods to monitor client connections for server applications.

• Methods to control application backup procedures.

• Methods to extract internal state information used in debugging.



• Methods to change various application configuration parameters.

• Methods that instruct applications to write their new configuration parameters to configuration files or to the Microsoft Windows registry.


Guidelines for AMI Programming | 31

Guidelines for AMI Programming

The following guidelines are recommendations on building an AMI application interface:

• Start slowly.

Don’t identify twenty methods and try to implement them all at once. Instead, get one method to work (for example, a getVersion method), then build on that. Interact with the application in the TIBCO Hawk Display or the AMI Workbench and make sure that everything is working as you expect. Then add other methods you would like to implement.

• Use consistent names.

Make sure you use the same names to describe method parameters and to return or interpret them. If you decide to change the string that displays in the manager when a user checks method parameters, you need to change the string in two places. It must be changed both in the place where you created the parameter descriptor message, and in the method itself, where you read the arguments or prepare the results. If these do not match, the method will not work correctly. Using string constants can help avoid this problem.

• Pay attention to requirements.

The AMI specification includes some absolute requirements. Your interface must adhere to these requirements, or errors will result. For example, you must always pass the CONTEXT field back in any message replying to a request from the manager. Review Chapter 3, The AMI Protocol, on page 33 and Chapter 4, AMI Message Reference, on page 51 to verify that you have satisfied all AMI requirements.

• Learn message structure.

To describe your methods, handle arguments, and return results, you must be familiar with the practice of nesting TIBCO Rendezvous messages. Read the book TIBCO Rendezvous Concepts (especially the section on message structure). To avoid confusion, use naming conventions that give you clues as to where the message belongs in the hierarchy of messages being bundled. For example, messages that describe methods can end with the suffix _MethodDesc , and messages that describe an argument can end with the suffix _ArgDesc .

• Combine repeated information.

As shown in the AMI Message Reference, many of the message formats exchanged are either identical with other formats, or use some of the same



data fields. You can use common code to construct portions of messages that are identical, and branch only for portions of messages that are unique.

• Report errors.

If you have an error handler in your code that is called whenever an exception is raised, consider sending an unsolicited message to the manager. This will give you the maximum amount of information at the time when you need it. If you maintain a debug level (with get and set methods), you can change how much information you receive from your error handler, while interacting with your application. This is a much more useful approach than recompiling each time an error is encountered.


| 33

Chapter 3 The AMI Protocol

The information in this chapter lays out the AMI protocol in detail, with references to message types defined in Chapter 4, AMI Message Reference, on page 51.

Topics

• AMI Initialization, page 34

• Interface Discovery, page 35

• Method Description, page 36

• Method Invocation, page 42

• Sending an Unsolicited Message, page 49

• Instrumented Applications and Flavoring, page 50


34 | Chapter 3 The AMI Protocol

AMI Initialization

The steps involved in initializing an AMI interface are:

1. Implement a callback function or method that satisfies the requirements of method invocation request messages.

2. Create an inbox subscription and register the callback created in step 1, to handle received messages.

3. Create a discovery response to return the application name and the inbox address generated in step 2.

4. Subscribe to _LOCAL._HAWK.AMI.DISCOVERY and register the discovery response with the subscription.

5. Publish an announcement message on the subject _LOCAL._HAWK.AMI.START.

Note: Only one callback needs to be created to handle all received messages. The method description request and subsequent method invocation requests have the same message structure.


Interface Discovery | 35

Interface Discovery

When the application starts, as a part of the mutual discovery of managers and applications, the application’s management interface sends out an announcement message (see the section, Announcement Message, on page 53) on _LOCAL._HAWK.AMI.START.

After the application starts up, discovery occurs in the following way:

1. The manager publishes a discovery request message (see the section, Discovery Request and Reply Messages, on page 55) to _LOCAL._HAWK.AMI.DISCOVERY. This occurs at manager startup.

2. The application's management interface receives the discovery request message and sends a discovery reply message to the reply subject. The format and content of a discovery reply message is identical to that used for an announcement message.

Note: This exchange does not involve a CONTEXT field in the messages, as is required for method description and other method invocations.



Method Description

The following sections describe the steps involved in the description of application methods to the manager.

Method Description Request Message

The manager sends a method description request message (see the section, Method Description Request Message, on page 57) to the inbox address of the interface.

Because the type of this method is identical to the type of method invocation request messages, one callback method can handle both the _describeMethods call and invocation of user-defined methods.

Method Description Reply Message

The application's management interface receives the method description request message and sends a method description reply message (see the section , Method Description Reply Message, on page 58) to the reply subject. The reply is a nested TIBCO Rendezvous message that describes all supported methods, their arguments, and their return values.

The reply must fully describe all supported methods, with the following exceptions:

• The mandatory _describeMethods and _heartbeat methods need not be described.

• If implemented, the optional methods _startRepeatingMethod and _stopRepeatingMethod must appear in the method description reply message, to tell the manager that the application supports them. However, because they have a fixed format, they need not have their arguments or return values described.


Method Description | 37

_describeMethods Message Response

The response to the _describeMethods call is a message similar to the following outline, with messages marked with a > symbol. Optional parts are marked with an asterisk. The items shown in bold are described in more detail following this section.

Returned Item DescriptionThe sections below describe some of the most important returned items.

> The message describing methods includes:ERROR : whether an error occurred while trying to describe the methodsERROR_MSG : what to say to the user about the error *(if an error occurred, nothing else is required)CONTEXT : an integer sent by the manager that the application simply sends backRETURNS : a list of method descriptors

> Each method descriptor is a message including:NAME : the name of the methodHELP : a string to display in a GUI describing the method *TYPE : the type of method: INFO , ACTION , or ACTION_INFO *TIMEOUT : the invocation timeout value*ARGUMENTS : a list of parameter descriptors *

> Each parameter descriptor is a message including:NAME : the unique name of the argumentSAMPLE_VALUE : a sample value of the correct typeHELP : a help string to display describing the argument * VALUE_CHOICES :

> a list of possible choices for the argument *LEGAL_VALUE_CHOICES :

> a list of legal choices for the argument *RETURNS : a list of parameter descriptors *

> Each parameter descriptor is a message including:NAME : the unique name of the result fieldSAMPLE_VALUE : a sample value of the correct typeHELP : a help string to display describing the result field *

INDEX : an index result field that is unique across multiple result records *



ERROR

If your method has a problem responding to the call to describe its methods, it cannot carry out the request. Methods that cannot respond should return a true value for the error flag, then return an error string telling why the method could not finish its operation. If the error flag is true, the manager displays the error string and ignores the rest of the message.

TYPE

You can avoid explicitly specifying the type of method by following these method-naming conventions:

• A method starting with get returns information only and is assumed to be of type INFO .

• A method starting with set or do takes action only and is assumed to be of type ACTION .

• A method with any other name both takes action and returns information and is assumed to be of type ACTION_INFO .

If this convention is not used, specify a method type with each method descriptor. By providing the method type, you are free to change method names without updating the specified type. However, by using the naming convention, the method type need not be specified. Override the default method type by supplying this field only when it must be directly specified.

TIMEOUT

The timeout specifies how long a manager should wait for an invocation of this method to complete. In order to achieve the desired loose coupling between managers and managed applications, the manager cannot wait indefinitely for a method invocation in a managed application. This would potentially allow a managed application to hang the manager. If this timeout period expires, the manager will reflect a timeout error within the management application. Should the method subsequently return the result of the invocation, the manager will simply discard it.

The timeout value is specified in milliseconds. The timeout is an optional field and defaults to 10000 milliseconds (10 seconds). The default value should be sufficient for the majority of methods. However, if your method is causing timeout errors you can adjust the timeout accordingly. Remember that a primary goal in creating managed applications is to design methods that respond quickly when invoked.



SAMPLE_VALUE

Instead of returning a type identifier, return a representative sample of a TIBRVMSG_STRING , TIBRVMSG_I32 , TIBRVMSG_F64 , or TIBRVMSG_BOOL .

Examples might be:

• For a string, return a TIBRVMSG_STRING containing "this is a sample string" .

• For an integer, return a TIBRVMSG_I32 containing a zero.

• For a floating point number, return a TIBRVMSG_F64 containing the value 0.0.

• For a boolean, return a TIBRVMSG_BOOL containing a TRUE value.

U64 Support and java.math.BigInteger

Unsigned 64 bit integer values (and larger unsigned integer values) can be used in AMI as method argument and return parameters. Because the TIBCO Hawk agent is implemented in Java and there is no U64 support in Java, the java.math.BigInteger class is used to represent these values.

U64 (and larger) integers are transmitted as method arguments and returns using the TIBRVMSG_OPAQUE type, which is essentially a byte array. This array must contain the two's-complement representation of the number. The array must be big-endian (most significant byte is in the [0] position). Java applications implementing the AMI protocol can easily convert between this representation and the BigInteger type by using the supported constructors and methods of BigInteger.

Describing a Method that Uses BigInteger

The SAMPLE_VALUE field of a Parameter Descriptor Message accepts an additional type, TIBRVMSG_OPAQUE . If this type is used as a sample value, the VALUE_TYPE field value must be java.math.BigInteger.

Invoking a Method that Uses BigInteger

Parameter List Messages, which are used to represent method arguments and returns in method invocations, can also handle the additional TIBRVMSG_OPAQUE type. Construct or interpret the byte array as described above to exchange large unsigned integer values.



VALUE_CHOICES, LEGAL_VALUE_CHOICES

Possible choices are presented in an editable combo box: one which allows selection of one item or typing in of a new item. Legal choices are presented in a non-editable combo box, one in which you cannot specify a new item. Which to use for a particular argument depends on whether you can process values not in your list. You can present either type of choice, but not both. If both lists are included, the legal choices override the possible choices and a value cannot be entered.

RETURNS

A method result can be split into any number of result fields. In the TIBCO Hawk Display or AMI Workbench, a list of result fields appears as columns in a table. You can see how multiple result fields are used by viewing method results returned by built-in microagents. To describe multiple result fields, place messages describing them inside the method-descriptor message, as you would do for method arguments.

INDEX

A method result can contain not only multiple result fields (to return a list), but also multiple result records (to return a table). Usually, each record in the table pertains to a discrete instance in a group of like objects being monitored, such as a client connection or internal message queue. If you create a test based on the result of the method invocation, either through a network query or through a rulebase, the test will apply independently to each record in the table.

To describe a situation in which you will return multiple result records, tell the manager which result field is unique to each record by specifying the name of the result field as the INDEX field of the method descriptor message. The manager tracks result records in this column and keeps their identities separate.

Multiple INDEX entries can be specified to define a composite key consisting of multiple result fields.

Even though the capability is provided, there is no need to return multiple result fields and records. You might start by returning only single values. When a simple system is working well, you can add multiple result fields and records as needed.

The use of curly brackets { } in microagent method parameter names is not supported. Use of these characters results in an error.



An Example of Returning a Table of DataYou might be using AMI to monitor a server application that deals with multiple client applications. You make visible a method called getClientInfo , which returns a result table. Each record of the table describes a single currently-connected client. The number of records in the table can vary from over time, depending on how many clients are connected.

To set this up, you define three parameter descriptor messages with the names clientID , clientConnectionTime , and clientLoadAverage . For the INDEX field, you specify the string clientID . This tells the manager that the entry in the clientID field of each result record is unique to that record.

Now, using the TIBCO Hawk Display, you create a rule in a rulebase that raises an alarm if the result field clientLoadAverage exceeds a threshold. You specify that the test be applied every five minutes. Even though only created one rule and one test was created, the TIBCO Hawk agent independently applies the test to each client with a unique clientID field.



Method Invocation

Method invocation messages from the manager have a structure similar to the outline below. (The overall message structure is the same as that is used to invoke the _describeMethods method. These methods can thus be handled in the same callback function.)

The application receives this message through its callback function. The message is received as an argument to the callback function call.

The application examines the message and calls the correct internal method to create a message to return the requested information. The application typically dispatches the message to one of its internal methods (usually the methods described in _describeMethods), and the internal method returns a message to the manager.

When a manager invokes any method, an immediate reply is expected. However, the manager allows a grace period of ten seconds before timing out and reporting an error.

Notice that all method invocation requests, whether reserved or user-defined, have the same three fields in their top level TIBRVMSG structure, as shown in Table 2.

> The message from the manager to the application invoking a method includes:NAME : the name of the method the manager is to callCONTEXT : an integer sent by the manager that the application simply sends backARGUMENTS : a list of method arguments (using the format declared

by the application in the _describeMethods message)> Each method argument is a message including:

the name of the argument the data for the argument (a string, integer, real number or boolean)

Table 2 Common Fields in All Method Invocation Requests

Field Description

NAME The name of the method the manager is to call; in the case of method description, this is always _describeMethods.

CONTEXT An integer sent by the manager, sent back by the application.

ARGUMENTS A list of method arguments; in the case of method description, this is an empty message.


Method Invocation | 43

Application management interfaces can therefore do the initial processing of all messages in the same way and then branch off to handle each message based on NAME .

If no argument is specified when a method is invoked (by a user or agent), the defaults shown in Table 3 are used.

The message returned from the application to the manager has a structure like this outline.

The name of each result field must match the names specified in the _describeMethods method, and the type of each data item for a result field must match the type specified using the sample value in the _describeMethods method.

Replies to all method invocations, whether reserved or user-defined, use the same field structure in their top level TIBRVMSG , as shown in Table 4. Interfaces can therefore use common code to construct the top level of all replies.

Table 3 Default Arguments for User-Defined Methods

Message type Default

TIBRVMSG_I32 0 (zero)

TIBRVMSG_F64 0.0 (zero)

TIBRVMSG_STRING "" (empty string)

TIBRVMSG_BOOL TRUE

> The message from the application to the manager responding to a method call includes:ERROR : whether an error occurred while trying to carry out the method callERROR_MSG : what to say to the user about the error *(if an error occurred, nothing else is required)CONTEXT : an integer sent by the manager that the application simply sends backRETURNS : a list of result records *

> Each result record is a message including:a list of result fields

> Each result field is a message including:the name of the result field the data for the result field for this result record

Table 4 Common Fields in All Method Invocation Replies

Field Description

ERROR Whether an error occurred while trying to carry out the method call.



The one message that uses a different field structure is a heartbeat reply message, which includes only the CONTEXT field. Since the manager ignores any additional fields, heartbeat replies may also include the common header if it makes implementation easier.

Method Invocation of Reserved MethodsReserved methods are those that begin with "_". Their invocation is basically the same as that for user-defined methods with the exception that the message structures are fixed. Manager requests are sent to the same inbox address that all method invocation requests are sent to.

Reserved methods can be divided into:

• Required methods.

• Optional methods.

Method Invocation of Required Reserved MethodsThere are two required methods:

• _describeMethods • _heartbeat

Invocation of _describeMethods

Invocation of _describeMethods is described in Method Description on page 36.

Invocation of _heartbeat

The _heartbeat method is invoked with a heartbeat request message (see Heartbeat Request and Reply Messages on page 75) in a similar manner to user-defined methods. A heartbeat reply message is sent back to the reply subject and contains only a CONTEXT field.

ERROR_MSG What to say to the user about the error.

CONTEXT An integer sent by the manager that the application simply sends back.

RETURNS A list of result records; in the case of method description, this is a list of method descriptor messages.

Table 4 Common Fields in All Method Invocation Replies (Cont’d)

Field Description



Method Invocation of Optional Reserved MethodsThere are four optional reserved methods:

• _startRepeatingMethod • _stopRepeatingMethod

• _startAsyncMethod

• _stopAsyncMethod

Invocation of _startRepeatingMethod

A repeating method invocation request message (see Repeating Method Invocation Request Message on page 77) includes:

• The method name _startRepeatingMethod .

• The collection interval.

• The number of times your application should respond.

• The reply subject.

• An TIBRVMSG structure that defines the user-defined method to invoke repeatedly. This enclosed method invocation request message is identical to the TIBRVMSG structure that the manager uses to invoke the specified method a single time.

On receiving this message, the application should start a timer and begin periodically sending out messages answering the embedded method call. The messages sent back should be identical to those sent if the embedded method call was not repeated. Send the first response immediately, and send others at the supplied interval, until the requested number of responses has been sent. Report any errors encountered in servicing the request in your reply as though it were a single method invocation.

As with all method invocation replies, a context field must be returned. This is the value of the CONTEXT field specified in the enclosed method invocation request.

All replies from the repeating method must be sent to the reply subject contained in the ARGUMENTS list of the _startRepeatingMethod method invocation. The reply to the _startRepeatingMethod invocation itself must be sent to the reply subject of the request.



When invoking _startRepeatingMethod , the manager allows a grace period of ten seconds for the receipt of the first message. Each additional reply in the sequence is allowed a grace period of ten seconds over the collection interval from the time of the previous reply. If the manager encounters any errors related to the use of _startRepeatingMethod, such as timing out, it reports the error and discontinues using the repeating method call. It then resorts to polling, as if _startRepeatingMethod was not implemented.

If the _startRepeatingMethod method is provided, the manager may also use it to periodically invoke the _heartbeat method so that it doesn't have to poll for heartbeats.

Invocation of _stopRepeatingMethod

A stop repeating message request message (see Stop Repeating Method Invocation Request Message on page 79) is sent by the manager to request that the application stop sending a message in a series initiated by a _startRepeatingMethod call. Supporting this method is not mandatory, as the series of messages should terminate on its own. (However, response is mandatory if the method has been described to the manager.)

The application responds by sending a stop repeating message reply message , which is identical to the standard method invocation reply message when the method invoked does not return any results.

If you implement _stopRepeatingMethod , you need to store the reply subject of the repeat request, along with the context, and use them as a key to identify the request. The manager uses them to identify what _startRepeatingMethod call should be stopped. For example, an application might respond to one repeating method call and then respond to another before the first has finished its iterations. If the application receives a _stopRepeatingMethod call, you must know which repeating method execution to stop.

Invocation of _startAsyncMethod

An asynchronous method invocation request message (see Start Async Method Invocation Request Message on page 81) includes:

• The method name _startAsyncMethod

• The duration

• The reply subject

• An TIBRVMSG structure that defines the user-defined method to invoke repeatedly. This enclosed method invocation request message is identical to the TIBRVMSG structure that the manager uses to invoke the specified method a single time.



On receiving this message, the application should send the first response to this message immediately. The application should send data from the requested asynchronous method whenever it becomes available. Report any errors encountered in servicing the request in your reply as though it were a single method invocation. It is the responsibility of the manager to refresh the subscription before the initial request expires after duration seconds. To refresh the subscription, the manager must send yet another _startAsyncMethod invocation containing the same arguments as the original method invocation.

As with all method invocation replies, a context field must be returned. This is the value of the CONTEXT field specified in the enclosed method invocation request.

All replies from the asynchronous method must be sent to the reply subject contained in the ARGUMENTS list of the _startAsyncMethod method invocation. The reply to the _startAsyncMethod invocation itself must be sent to the reply subject of the request.

If the _startAsyncMethod is implemented, your application must store the reply subject and the context to uniquely identify each method invocation request. If the application receives a method invocation request with the same reply subject and context values before the original expires, it is treated as a refresh of the original request and the new value of duration is used.

Invocation of _stopAsyncMethod

A stop async message request message (see Stop Async Method Invocation Request Message on page 84) is sent by the manager to request that the application stop sending a message in a series initiated by a _startAsyncMethod call. Supporting this method is not mandatory, as the series of messages should terminate on its own. (However, response is mandatory if the method has been described to the manager.)

The application responds by sending a stop async message reply message, which is identical to the standard method invocation reply message when the method invoked does not return any results.

The application uses the reply subject and index values to determine which asynchronous method subscription should be stopped.

Method Invocation of User-Defined Methods

User-defined methods fall into three groups based on outcome:

• INFO methods collect data. Data sources in rulebases and method subscriptions in the TIBCO Hawk Display use this type of method only.

• ACTION methods affect the application’s behavior in some way. They can be invoked in the TIBCO Hawk Display through interacting with one agent or



through a network action. Action methods can also be invoked as an action in a rulebase.

• ACTION_INFO methods both make a change to the application and return data. They can be invoked in the TIBCO Hawk Display through interacting with one agent or through a network action.

The steps involved in invocation of user-defined methods are as follows:1. The manager publishes a method invocation request message (see Method

Invocation Request Message on page 68) to the interface's inbox address.

2. The application's management interface receives the method invocation request message, invokes a method (or similar action) and sends a method invocation reply message (see Method Invocation Reply Message on page 70) to the reply subject.


Sending an Unsolicited Message | 49

Sending an Unsolicited Message

An unsolicited message (see Unsolicited Message on page 87) is an application information, warning, or error message that is sent from the managed application directly to the manager. These can be sent at any time the managed application is to notify the manager of some event. These messages are sent to subject name _LOCAL._HAWK.AMI.INFO . An unsolicited message has these parts:

• The message type (INFO , WARNING , or ERROR).

• The message text.

• An ID number to identify messages and which can be tested for in rulebases.

• The inbox address you use to communicate with the manager. It identifies the message origin.



Instrumented Applications and Flavoring

TIBCO Rendezvous software is licensed using license tickets, which are character strings that encode licensing information. License tickets are stored in files such as tibrv.tkt (for the TIBCO Rendezvous daemon and routing daemon). TIBCO Hawk employs an embedded TIBCO Rendezvous license that allows the TIBCO Hawk software to use the TIBCO Rendezvous solely in support of the TIBCO Hawk product. A TIBCO Rendezvous license ticket is not required to run the TIBCO Hawk product with the TIBCO Rendezvous daemon (rvd). The use of TIBCO Hawk with the TIBCO Rendezvous routing daemon (rvrd), however, still requires a valid TIBCO Rendezvous license ticket.

The AMI APIs allow applications to be AMI instrumented so that they use the same embedded TIBCO Rendezvous license as the TIBCO Hawk product. This license only allows the AMI instrumented application to use TIBCO Rendezvous in support of the AMI communication with the TIBCO Hawk agent. Any other use of TIBCO Rendezvous by the AMI application would require a valid TIBCO Rendezvous license ticket.


| 51

Chapter 4 AMI Message Reference

This chapter describes message formats used in the initialization and operation of an AMI interface for an application. Before referring to this chapter, you should review AMI Concepts on page 7. The messages are shown here in chronological order in terms of the AMI conversation, though some messages nest.

Topics

• Introduction to the Messages, page 52

• Announcement Message, page 53

• Discovery Request and Reply Messages, page 55

• Method Description Request Message, page 57

• Method Description Reply Message, page 58

• Method Descriptor Message, page 60

• Parameter Descriptor List Message, page 63

• Parameter Descriptor Message, page 66

• Method Invocation Request Message, page 68

• Method Invocation Reply Message, page 70

• Parameter List Message, page 72

• Returning Results in the Form of Tables, page 74

• Heartbeat Request and Reply Messages, page 75

• Repeating Method Invocation Request Message, page 77

• Stop Repeating Method Invocation Request Message, page 79

• Start Async Method Invocation Request Message, page 81

• Stop Async Method Invocation Request Message, page 84

• Stop Message, page 86

• Unsolicited Message, page 87


52 | Chapter 4 AMI Message Reference

Introduction to the Messages

Figure 9 shows how some of the messages described in this chapter are sent between a managed application and its manager.

Figure 9 Messages Sent During an AMI Conversation

Managed A

pplication

Man

ager

Phase 1: Discovery(one scenario:

application starts first)

Phase 2: Method Description

Phase 3: Method Invocation


Send methoddescription request



Reply to methoddescriptionrequest


Tim

eRequest method

invocation





Announcement Message | 53

Announcement Message

An announcement message is sent when an application instrumented with AMI announces its presence to any managers already running when the application starts. Since the message is sent locally (to _LOCAL._HAWK.AMI.START), only managers connected to the same TIBCO Rendezvous daemon receive the message.

Figure 10 Structure of an Announcement Message

The structure of an announcement message is identical to that of a discovery reply message (see Discovery Request and Reply Messages on page 55).

TIBRVMSG:TIBRVMSG_STRING - "APP_NAME"TIBRVMSG_STRING - "DISPLAY_NAME"TIBRVMSG_STRING - "INBOX"TIBRVMSG_STRING - "AMI_VERSION"TIBRVMSG_STRING - "HELP"

AMI reply: AMI Discovery Reply Message

Manager Request: AMI Discovery Reply Message

TIBRVMSG:TIBRVMSG_STRING - "MANAGER_NAME"

Table 5 Format of Announcement Messages

Field Name Type Description

APP_NAME TIBRVMSG_STRING The application's (interface's) name. To avoid possible name collisions, application names should contain the domain name of the originating organization. For example, TIBCO's TIC should be named COM.TIBCO.TIC .

DISPLAY_NAME TIBRVMSG_STRING The application’s (interface’s) user-friendly name. This name is used for display purposes only, in console application GUIs such as the TIBCO Hawk Display. Unlike APP_NAME , the DISPLAY_NAME is purely for display purposes. Thus, it does not have to be unique.

INBOX TIBRVMSG_STRING The name of the inbox used for method description and method invocation. Also referred to as an inbox address.

AMI_VERSION TIBRVMSG_STRING The version number of this specification.



HELP TIBRVMSG_STRING A short description of this application suitable for display in a GUI. It is recommended that this string contain at least the application name and the application version number. For example, TIC Version 3.7 .

Table 5 Format of Announcement Messages



Discovery Request and Reply Messages | 55

Discovery Request and Reply Messages

If the managed application starts before the manager, the application declares its interest in the local AMI discovery subject (_LOCAL._HAWK.AMI.DISCOVERY). When the manager starts it sends out a message on that subject, and the application replies.

Figure 11 Structure of Discovery Request and Reply Messages

The structure of a discovery reply message is identical to that an announcement message (see Announcement Message on page 53).

TIBRVMSG:TIBRVMSG_STRING - "APP_NAME"TIBRVMSG_STRING - "DISPLAY_NAME"TIBRVMSG_STRING - "INBOX"TIBRVMSG_STRING - "AMI_VERSION"TIBRVMSG_STRING - "HELP"

AMI reply: AMI Discovery Reply Message

Manager Request: AMI Discovery Reply Message

TIBRVMSG:TIBRVMSG_STRING - "MANAGER_NAME"


MANAGER_NAME TIBRVMSG_STRING Identifies the manager. The managed application can ignore this field.

APP_NAME TIBRVMSG_STRING The application's (interface's) name. To avoid possible name collisions, application names should contain the domain name of the originating organization. For example, TIBCO's TIC should be named COM.TIBCO.TIC .

DISPLAY_NAME TIBRVMSG_STRING The application’s (interface’s) user-friendly name. This name is used for display purposes only, in console application GUIs such as the TIBCO Hawk Display. Unlike APP_NAME , the DISPLAY_NAME is purely for display purposes. Thus, it does not have to be unique.

INBOX TIBRVMSG_STRING The name of the inbox used for method description and method invocation. Also referred to as an inbox address.

AMI_VERSION TIBRVMSG_STRING The version number of this specification.



HELP TIBRVMSG_STRING A short description of this application suitable for display in a GUI. It is recommended that this string contain at least the application name and the application version number. For example, TIC Version 3.7 .



Method Description Request Message | 57

Method Description Request Message

A method description request message is sent from the manager to the application when it asks the application to describe its supported message exchanges.

Figure 12 Structure of a Method Description Request Message

This message is identical to that used in the method invocation phase (see Method Invocation Request Message on page 68) except that _describeMethods is specifically invoked.

Manager Request: Method Description Request Message

TIBRVMSG:TIBRVMSG_STRING - "NAME"="_describeMethods"TIBRVMSG_STRING- 'ARGUMENTS"=empty TIBRVMSGTIBRVMSG_I32-"CONTEXT"

Table 6 Format of Method Description Request Message

Field Name Type Value Description

NAME TIBRVMSG_STRING "_describeMethods” Identifies the method. All management interfaces must support the _describeMethods method.

CONTEXT TIBRVMSG_I32 (4bytes)

can be any integer This context integer is simply returned in the CONTEXT field of the reply to this request.

ARGUMENTS TIBRVMSG_MSG empty TIBRVMSG Unused for method _describeMethods but included as an empty TIBRVMSG for consistency with all other method invocations.

MSG_TYPE TIBRVMSG_STRING Reserved for future use.



Method Description Reply Message

A method description reply message is sent by the application to its manager in order to describe its methods. This message is sent in response to a request for description of supported message exchanges.

Figure 13 Structure of a Method Description Reply Message

AMI Reply: Method Description Reply Message

TIBRVMSG:TIBRVMSG_BOOL - "ERROR"TIBRVMSG_STRING - "ERROR_MSG"TIBRVMSG_I32 - "CONTEXT"TIBRVMSG_MSG - "RETURNS (Multiple "RETURNS" fields, each describes one method)

TIBRVMSG:TIBRVMSG_STRING - "NAME"TIBRVMSG_MSG - "ARGUMENTS"TIBRVMSG_MSG - "RETURNS"TIBRVMSG_STRING - "INDEX"TIBRVMSG_STRING - "HELP"TIBRVMSG_STRING - "TYPE"TIBRVMSG_BOOL - "SYNCHRONOUS"TIBRVMSG_I32 - "TIMEOUT". ..

TIBRVMSG: (list of parameter descriptors)TIBRVMSG_MSG - "PARAMETER_DESCRIPTOR". ..

TIBRVMSG:TIBRVMSG_STRING - "NAME"TIBRVMSG_STRING/INT/REAL - "SAMPLE_VALUE"TIBRVMSG_STRING - "HELP"TIBRVMSG_MSG - "VALUE_CHOICES"TIBRVMSG_MSG - "LEGAL_VALUE_CHOICES"

Method Descriptor

Parameter List

Parameter Descriptor


Method Description Reply Message | 59

Under this message is nested method descriptor messages (see Method Descriptor Message on page 60), each of which nests a parameter descriptor list message (see Parameter Descriptor List Message on page 63), which nests parameter descriptor messages (see Parameter Descriptor Message on page 66).

Table 7 Format of Method Description Reply Messages


ERROR TIBRVMSG_BOOL Indicates whether or not some error has occurred while attempting to process the method invocation.

ERROR_MSG TIBRVMSG_STRING Optional. The string describing the error. Ignored by the manager if ERROR is false.

CONTEXT TIBRVMSG_I32 The integer supplied in the CONTEXT field of the method description request message that triggered this reply. The management interface need simply return what it was given.

RETURNS TIBRVMSG_MSG There can be multiple RETURNS fields. Each one contains the description of a single supported method. See “Method Descriptor Message” on page 60.



Method Descriptor Message

A method descriptor message describes one method (message exchange) that the application is to make available to its manager.

Figure 14 Structure of a Method Descriptor Message



TIBRVMSG:TIBRVMSG_STRING - "NAME"TIBRVMSG_MSG - "ARGUMENTS"TIBRVMSG_MSG - "RETURNS"TIBRVMSG_STRING - "INDEX"TIBRVMSG_STRING - "HELP"TIBRVMSG_STRING - "TYPE"TIBRVMSG_BOOL - "SYNCHRONOUS"TIBRVMSG_I32 - "TIMEOUT". . .

TIBRVMSG: (list of parameter descriptors)TIBRVMSG_MSG - "PARAMETER_DESCRIPTOR". . .


Method Descriptor

Parameter List



Method Descriptor Message | 61

Method descriptor messages are sent to the manager inside the method description reply message sent from the _describeMethods method (see Method Description Reply Message on page 58).


NAME TIBRVMSG_STRING The name of the method being described. By convention, method names beginning with get are assumed to be of type INFO and those beginning with the strings set or do are assumed to be of type ACTION . All other prefixes imply type ACTION_INFO . See description of the optional TYPE field below.

ARGUMENTS TIBRVMSG_MSG A nested TIBRVMSG that describes all the arguments.

See “Parameter Descriptor List Message” on page 63. This field is optional. If omitted or set to an empty TIBRVMSG then method is assumed to require no arguments.

RETURNS TIBRVMSG_MSG A nested TIBRVMSG that describes the return parameters. See “Parameter Descriptor List Message” on page 63. This field is ignored (and thus optional) if the value of the TYPE field (or the implied type) is ACTION .

SYNCHRONOUS TIBRVMSG_BOOL Indicates whether or not the method returns data synchronously or asynchronously. Default is true.

TIMEOUT TIBRVMSG_I32 The timeout specifies how long a manager should wait for an invocation of this method to complete. If this interval is exceeded, a timeout error occurs at the manager. The timeout value is specified in milliseconds. The timeout is an optional field, and defaults to 10,000 milliseconds (10 seconds). The default value should be sufficient for most methods. However, if your method is causing timeout errors, you can adjust the timeout accordingly.

INDEX TIBRVMSG_STRING Required only if the described method returns multiple RETURNS fields. Each RETURNS field can have multiple parameters and corresponds to a single row in a table of data. Multiple rows of a table can be represented by multiple RETURNS fields in the method reply. The value of INDEX must be the name of a parameter in RETURNS whose value is unique across multiple RETURNS fields. See “Returning Results in the Form of Tables” on page 74.

RETURN_CLASS TIBRVMSG_STRING Reserved for future use.

HELP TIBRVMSG_STRING A short description of the method’s purpose, suitable for display in a GUI.



TYPE TIBRVMSG_STRING Overrides the implicit type specified by the method naming convention (see NAME field). Must be one of ACTION , INFO , ACTION_INFO . ACTION indicates that this method simply takes some action (modifies application behavior or configuration) and has no useful return value. INFO indicates that this method returns data that suitable for monitoring. ACTION_INFO indicates that this method takes some action and returns data suitable for monitoring. This field controls whether the method appears as a choice for a rule’s data source (INFO ) and/or a rule’s action.



Parameter Descriptor List Message | 63

Parameter Descriptor List Message

A parameter descriptor list message is a message that embeds one parameter descriptor for each argument or result. In the case where a method has both arguments and results, two parameter descriptor lists are included, and the ARGUMENTS or RETURNS field specifies whether each list describes arguments or results.



Figure 15 Structure of a Parameter Descriptor List Message

This message is embedded in a method descriptor message (see Method Descriptor Message on page 60) and contains a list of parameter descriptor messages (see Parameter Descriptor Message on page 66).



TIBRVMSG:TIBRVMSG_STRING - "NAME"TIBRVMSG_MSG - "ARGUMENTS"TIBRVMSG_MSG - "RETURNS"TIBRVMSG_STRING - "INDEX"TIBRVMSG_STRING - "HELP"TIBRVMSG_STRING - "TYPE"TIBRVMSG_BOOL - "SYNCHRONOUS"TIBRVMSG_I32 - "TIMEOUT". . .



Method Descriptor

Parameter List



Parameter Descriptor List Message | 65

Table 8 Format of Parameter Descriptor List Message


PARAMETER_DESCRIPTOR

TIBRVMSG_MSG (Parameter Descriptor)

The value is a nested TIBRVMSG that describes a single parameter. No two parameters in a single parameter descriptor list can have the same name. See “Parameter Descriptor Message” on page 66.



Parameter Descriptor Message

A parameter descriptor message is sent from an application to its manager to describe one argument or result that belongs to one method.

Figure 16 Structure of a Parameter Descriptor Message



TIBRVMSG:TIBRVMSG_STRING - "NAME"TIBRVMSG_MSG - "ARGUMENTS"TIBRVMSG_MSG - "RETURNS"TIBRVMSG_STRING - "INDEX"TIBRVMSG_STRING - "HELP"TIBRVMSG_STRING - "TYPE"TIBRVMSG_I32 - "TIMEOUT". . .


TIBRVMSG:TIBRVMSG_STRING - "NAME"TIBRVMSG_STRING/I32/F64 - "SAMPLE_VALUE"TIBRVMSG_STRING - "HELP"TIBRVMSG_MSG - "VALUE_CHOICES"TIBRVMSG_MSG - "LEGAL_CHOICES"

Method Descriptor

Parameter List



Parameter Descriptor Message | 67

All of the parameter descriptor messages that make up the arguments or results for a method are nested inside a parameter descriptor list message (see Parameter Descriptor List Message on page 63).

Table 9 Format of Parameter Descriptor Message

Field Type Description

NAME TIBRVMSG_STRING The name of the parameter (argument or return).

SAMPLE_VALUE <TIBRVMSG type>

Must be one of: TIBRVMSG_STRING

TIBRVMSG_I32

TIBRVMSG_F64 TIBRVMSG_BOOL

TIBRVMSG_OPAQUE

The value of this field is only a dummy value. The type of this field should match the type of the actual parameter. The manager inspects this field to discover what type the parameter being defined will be. Since the relevant information being conveyed is its type, the actual value of this field is ignored. The manager will cast the value to the largest native type. For example, TIBRVMSG_I32 is cast to a 4-byte int and TIBRVMSG_F64 is cast to a double (8-byte).

HELP TIBRVMSG_STRING A short description of the parameter suitable for display in a GUI. For arguments, this description should help the user choose an appropriate value. For returns, it should help the user understand what the value means.

VALUE_TYPE TIBRVMSG_STRING See Describing a Method that Uses BigInteger on page 39 for details.

VALUE_CHOICES TIBRVMSG_MSG Valid only when this parameter descriptor is used to describe an argument as opposed to a return. The TIBRVMSG in this field should hold a list of values that can be used for the argument being described. The field name for the values is ignored by the manager and can be an empty string (""). The list is presented in a manager GUI in an editable combo box (i.e. the user can pick from one of these or supply another value).

LEGAL_VALUE_

CHOICES

TIBRVMSG_MSG Similar to VALUE_CHOICES except that the user is restricted to supplying only one of the legal values specified. LEGAL_VALUE_CHOICES and VALUE_CHOICES are mutually exclusive. If they are both supplied, VALUE_CHOICES is ignored and LEGAL_VALUE_CHOICES is used.



Method Invocation Request Message

A method invocation request message is sent from the manager to the managed application when the manager is to invoke a method of the application.

Figure 17 Structure of a Method Invocation Request Message

The arguments given in the message must conform to the arguments described in the _describeMethods method. The outer structure of this message (outside of the parameter list message, see Parameter List Message on page 72) is identical to that of a method description request message (see Method Description Request Message on page 57).

Manager Request: Method Invocation Request Message

TIBRVMSG:TIBRVMSG_STRING - "NAME"TIBRVMSG_I32- "CONTEXT"TIBRVMSG_MSG-"ARGUMENTS"

:

...

TIBRVMSG<param type> - <param name> - <value>...

Parameter List

Name Type Description

NAME TIBRVMSG_STRING Identifies the requested method.


This context integer is simply returned in the CONTEXT field of the reply to this request. Its value is transparent to the managed application.

ARGUMENTS TIBRVMSG_MSG Method arguments. The value is a nested TIBRVMSG that supplies the method parameters. See “Parameter List Message” on page 72. Can be an empty TIBRVMSG or omitted if the method doesn't require arguments.

If no argument value was given when invoking the method, the defaults are:

TIBRVMSG_I32 : zero (0)

TIBRVMSG_F64 : zero (0.0)

TIBRVMSG_STRING : an empty string ("")

TIBRVMSG_BOOL : TRUE


Method Invocation Request Message | 69

MSG_TYPE TIBRVMSG_STRING Reserved for future use.




Method Invocation Reply Message

A method invocation reply message is sent from a managed application to its manager when it is replying to a method call from the manager.

Figure 18 Structure of a Method Invocation Reply Message

The results returned in the message must conform to the arguments described in the _describeMethods method.

AMIReply: Method Invocation Request Message

TIBRVMSG:TIBRVMSG_BOOL - "ERROR"TIBRVMSG_STRING- "ERROR_MSG"TIBRVMSG_I32 - "CONTEXT"

:

...


Parameter List

TIBRVMSG_MSG - "RETURNS"

Table 10 Format of Method Invocation Reply Message


ERROR TIBRVMSG_BOOL Indicates whether or not an error has occurred while attempting to process the method invocation.

ERROR_MSG TIBRVMSG_STRING Optional. The string describing the error. Checked only if ERROR is true.

CONTEXT TIBRVMSG_I32 The integer supplied in the CONTEXT field of the method invocation request message that triggered this reply. The management interface need simply return what it was given.


Method Invocation Reply Message | 71

RETURNS TIBRVMSG_MSG Method result. Required only if the method type was not ACTION and the ERROR field was false. The value is a nested TIBRVMSG that supplies the return parameters. See “Parameter List Message” on page 72. The actual number of parameters and their names and types must match the definition for the return parameters specified by the interface’s reply to _describeMethods . Multiple RETURNS fields can be used to represent lists and tabular data only if the INDEX field was specified in the method descriptor. See “Returning Results in the Form of Tables” on page 74.

Table 10 Format of Method Invocation Reply Message




Parameter List Message

The parameter list message format is used in two places:

• A message with this format can be sent from a manager to a managed application to supply a list of arguments for a method call.

• A message with this format can be sent from an application to its manager to supply a list of results from a method call.

Figure 19 Structure of a Parameter List Message when Used to Send Arguments

When this message format is used to specify arguments, it is nested inside a message invocation request message (see Method Invocation Request Message on page 68).

Figure 20 Structure of a Parameter List Message when Used to Send Results

Manager Request: Method Invocation Request Message

TIBRVMSG:TIBRVMSG_STRING- "NAME"TIBRVMSG_I32 - "CONTEXT"

:

...


Parameter List

TIBRVMSG_MSG - "ARGUMENTS"

AMIReply: Method Invocation Reply Message

TIBRVMSG:TIBRVMSG_BOOL- "ERROR"TIBRVMSG_STRING - "ERROR_MSG"TIBRVMSG_I32 - "CONTEXT"TIBRVMSG_MSG - "RETURNS"

:

...


Parameter List


Parameter List Message | 73

When this message is used to specify results, it is nested inside a message invocation reply message (see Method Invocation Reply Message on page 70).

Table 11 Format of Parameter List Messages


<parameter name> <parameter type> The name is the parameter name identified in a parameter descriptor message of the method description phase. The type must match the type specified in the same descriptor. Legal values are TIBRVMSG_STRING , TIBRVMSG_I32 and TIBRVMSG_F64 . No two parameters in a parameter list can have the same name.



Returning Results in the Form of Tables

Methods can return lists or tabular data in the form of multiple RETURNS fields in their reply. Each RETURNS field is composed of a list of uniquely named parameters. Each RETURNS field in a reply with multiple RETURNS fields must have the exact same parameter names and types as described in the parameter descriptor list during method description. Thus returning a list of RETURNS equates to returning a table of information where each RETURNS field is a single record (row) of the table.

Each record in this table typically contains monitoring statistics corresponding to some instance (out of a list of object instances) in the managed application. A manager performing monitoring tracks the same instance of this object across multiple method invocations (same row across multiple tables) by using the INDEX field.

Any method that can potentially return multiple RETURNS must have defined the INDEX field in the method descriptor supplied during method description. If INDEX is not defined, the manager ignores and discards all but the first RETURNS field in the reply. The value of INDEX is the name of one of the fields in RETURNS whose value must be unique across all RETURNS in a single reply.

Another way to describe this is that INDEX identifies a column in the table whose value can be used to uniquely index each row of the table. A row with the same index in successive tables forms a thread across method invocations that corresponds to the same unique monitored instance. If none of the columns naturally has unique values across each row, you should create one artificially. Multiple INDEX fields may be present in the method descriptor to indicate a combination of multiple columns that are used to uniquely index a row.


Heartbeat Request and Reply Messages | 75

Heartbeat Request and Reply Messages

A heartbeat request is sent from a manager to a managed application periodically to check to see if it is still active. The application replies with a heartbeat reply. If the manager receives no reply to a heartbeat request within a period of time, it de-registers the application.

Figure 21 Structure of a Heartbeat Request Message

Figure 22 Structure of a Heartbeat Reply Message

Additional fields such as ERROR can also be included in the heartbeat reply message for consistency with other reply messages. The manager will simply ignore them.

Manager Request:Heartbeat Request Message

TIBRVMSG:TIBRVMSG_STRING- "NAME"="_heartbeat"TIBRVMSG_MSG - "ARGUMENTS"=empty TIBRVMSGTIBRVMSG_I32 - "CONTEXT"

AMI Reply: Heartbeat Reply Message

TIBRVMSG:TIBRVMSG_INT - "CONTEXT"= the value of the "CONTEXT"field in the request

Table 12 Format of Heartbeat Request Messages

Name Type Value Description

NAME TIBRVMSG_STRING _heartbeat This is a required method.

ARGUMENTS TIBRVMSG_MSG empty TIBRVMSG An empty TIBRVMSG .

CONTEXT TIBRVMSG_I32 can be any integer This context integer is simply returned in the CONTEXT field of the reply to this request. Its value is transparent to the managed application.



Table 13 Format of Heartbeat Reply Messages


CONTEXT TIBRVMSG_I32 The integer supplied in the CONTEXT field of the heartbeat request message that triggered this reply. The management interface need simply return what it was given.


Repeating Method Invocation Request Message | 77

Repeating Method Invocation Request Message

A repeating method invocation request is sent from a manager to a managed application when the manager requests the application to carry out a method repeatedly, on a periodic basis. This message will only be sent if the application has declared its ability to respond to this type of repeating method call in the _describeMethods method.

The most important items in the message are the method, the number of times to call the method, and the time period to wait between sending replies. The application will be responsible for repeatedly calling the method. The message sent should be identical to a normal (non-repeating) method invocation reply. The first response should be sent immediately, and successive responses should be sent after each time interval.

Figure 23 Structure of a Repeating Method Invocation Request Message

Manager Request: Repeating Method Invocation Request Manager

TIBRVMSG:TIBRVMSG_STRING - "NAME"="_startRepeatingMethod"TIBRVMSG_I32 - "CONTEXT" InvocationRequestMessageTIBRVMSG_MSG - "ARGUMENTS"

TIBRVMSG:TIBRVMSG_I32 - "INTERVAL"TIBRVMSG_I32 - "REPEAT_COUNT"TIBRVMSG_STRING - "REPLY_SUBJECT"TIBRVMSG_MSG - "METHOD"

TIBRVMSG:TIBRVMSG_STRING - "NAME"TIBRVMSG_I32 ="CONTEXT"TIBRVMSG_MSG - "ARGUMENTS"

TIBRVMSG:<param type> - <param name> - <value>...

Arguments to "_startRepeatingMethods"


Parameter List



Nested inside this message will be a method invocation request message (see Method Invocation Request Message on page 68).

Table 14 Format of Repeating Method Invocation Request Messages


NAME TIBRVMSG_STRING _startRepeating

Method

This method is only supported if it was described in _describeMethods .


can be any integer This context integer is simply returned in the CONTEXT field of the reply to this request. Its value is transparent to the managed application.

ARGUMENTS TIBRVMSG_MSG A nested TIBRVMSG with the fields shown in the following table.

Table 15 Format of Arguments to _startRepeatingMethods


INTERVAL TIBRVMSG_I32

(4bytes)can be any integer The time between repeated method

invocations, in seconds.

REPEAT_

COUNT

TIBRVMSG_I32 (4bytes)

can be any integer The number of times to repeat the method call. The application should keep track of repeated returns and stop when this number is reached.

REPLY_

SUBJECT

TIBRVMSG_STRING can be any string The subject to which all replies from the repeating method should be sent.

METHOD TIBRVMSG_MSG A nested method invocation request message (See “Method Invocation Request Message” on page 68.)

The value is identical to a method invocation request message that would be sent without a request to repeat.


Stop Repeating Method Invocation Request Message | 79

Stop Repeating Method Invocation Request Message

A stop repeating method request message is sent by a manager to an application when it asks the application to stop repeating a method call that the manager had previously asked the application to start. The manager usually does this when it no longer wants the data. The application should reply with a message as if it were answering a method invocation call for a method with no results.

Figure 24 Structure of a Stop Repeating Method Request and Reply Messages

Manager Request: Stop Repeating Method Invocation Request Message

TIBRVMSG:TIBRVMSG_STRING - "NAME"="_startRepeatingMethod"TIBRVMSG_I32 - "CONTEXT" - of the stop request itselfTIBRVMSG_MSG - "ARGUMENTS"

TIBRVMSG:TIBRVMSG_STRING - "REPLY_SUBJECT"TIBRVMSG_I32 - "CONTEXT" of the Repeating Method thatis to be stopped

Arguments to "_startRepeatingMethods"


NAME TIBRVMSG_STRING _stopRepeating

Method



Can be any integer The context of the stop request itself.


REPLY_

SUBJECT

TIBRVMSG_STRING Can be any string The reply subject of the original _startRepeatingMethod request. Used to indicate which method request should be stopped.




can be any integer The context of the repeating method that is to be stopped. If the management interface chooses to also implement _stopRepeatingMethod then it must store the reply subject of the repeat request along with the context and use them as an key to identify the request, because this is how _stopRepeatingMethod indicates what is to be stopped. Management interfaces should reply to the reply subject in the standard format which includes an error flag. The RETURNS field is ignored and can be an empty TIBRVMSG .



Start Async Method Invocation Request Message | 81

Start Async Method Invocation Request Message

The _startAsyncMethod method may be used by the manager to subscribe to data provided by any of the asynchronous user defined methods. This message will only be sent if the application has declared its ability to respond to this type of method call in the _describeMethods method.

The most important items in this message are the method and the time duration for which the manager is interested in data coming from the asynchronous method. The message sent should be identical to a normal (non-repeating) method invocation reply. The first response should be sent immediately, and successive responses should be sent for the period of time specified by the duration .


NAME TIBRVMSG_STRING _stopRepeating

Method



can be any integer The context of the stop request itself.


REPLY_

SUBJECT

TIBRVMSG_STRING can be any string The reply subject of the original _startRepeatingMethod request. Used to indicate which method request should be stopped.


can be any integer The context of the repeating method that is to be stopped. If the management interface chooses to also implement _stopRepeatingMethod then it must store the reply subject of the repeat request along with the context and use them as an key to identify the request, because this is how _stopRepeatingMethod indicates what is to be stopped. Management interfaces should reply to the reply subject in the standard format which includes an error flag. The RETURNS field is ignored and can be an empty TIBRVMSG .



Figure 25 Structure of a Start Async Method Invocation Request Message

Nested inside this message will be a method invocation request message (see Method Invocation Request Message on page 68).

Manager Request: Async Method Invocation Request Message

TIBRVMSG:

TIBRVMSG_I32 - "CONTEXT" InvocationRequestMessageTIBRVMSG_MSG - "ARGUMENTS"

TIBRVMSG:TIBRVMSG_I32 - "DURATION"TIBRVMSG_STRING - "REPLY_SUBJECT"TIBRVMSG_MSG - "METHOD"

TIBRVMSG:TIBRVMSG_STRING - "NAME"TIBRVMSG_I32="CONTEXT"TIBRVMSG_MSG - "ARGUMENTS"

TIBRVMSG:<param type> - <param name> - <value>...

Arguments to "_startAsyncMethods"


Parameter List

TIBRVMSG_STRING-"NAME"="_startAsyncMethod"

Table 16 Format of Arguments to _startAsyncMethods

Field Type Value Description

NAME TIBRVMSG_STRING _startAsync

Method



can be any integer This context integer is simply returned in the CONTEXT field of the reply to this request. Its value is transparent to the managed application.


Start Async Method Invocation Request Message | 83

ARGUMENTS TIBRVMSG_MSG A nested TIBRVMSG with the fields shown in Table .

A nested TIBRVMSG that describes all the arguments.

Table 17 Format of Method Invocation Request Messages


DURATION TIBRVMSG_I32

(4bytes)can be any integer The time period in seconds for which

the manager is requesting data from the asynchronous method.

REPLY_

SUBJECT

TIBRVMSG_STRING can be any string The subject to which all replies from the asynchronous method should be sent.

METHOD TIBRVMSG_MSG A nested method invocation request message (See “Method Invocation Request Message” on page 68.)

The value is identical to a method invocation request message that would be sent without a request to repeat.

Table 16 Format of Arguments to _startAsyncMethods

Field Type Value Description



Stop Async Method Invocation Request Message

A stop async method request message is sent by a manager to an application when it asks the application to stop subscribing to the specified method. The manager usually does this when it no longer wants the data. The application should reply with a message as if it were answering a method invocation call for a method with no results.

Figure 26 Structure of a Stop Async Method Request Message

Manager Request: Stop Async Method Invocation Request Message

TIBRVMSG:

TIBRVMSG_I32 - "CONTEXT" - of the stop request itselfTIBRVMSG_MSG - "ARGUMENTS"

TIBRVMSG:

TIBRVMSG_STRING - "REPLY_SUBJECT"

Arguments to "_stopAsyncMethod"

TIBRVMSG_STRING-"NAME"="_stopAsyncMethod"

TIBRVMSG_I32 - "CONTEXT" - of the Async method thatis to be stopped.


NAME TIBRVMSG_STRING _stopAsync

Method



can be any integer The context of the stop request itself.


REPLY_

SUBJECT

TIBRVMSG_STRING can be any integer The reply subject of the original _startAsyncMethod request. Used to indicate which method request should be stopped.


Stop Async Method Invocation Request Message | 85


can be any integer The context of the repeating method that is to be stopped. If the management interface chooses to also implement _stopAsyncMethod then it must store the reply subject of the repeat request along with the context and use them as an key to identify the request, because this is how _stopAsyncMethod indicates what is to be stopped. Management interfaces should reply to the reply subject in the standard format which includes an error flag. The RETURNS field is ignored and can be an empty TIBRVMSG .




Stop Message

A stop message is sent by the application to the manager before exiting. The advantage of using the stop message is that it allows the manager to know immediately when the application exits and that the application exited gracefully. Since the message is sent locally (to _LOCAL._HAWK.AMI.STOP), only managers connected to the same TIBCO Rendezvous daemon receive the message.

If the stop message is not used, the manager will eventually conclude that the application has terminated because it will stop responding to heartbeats.

Figure 27 Structure of a Stop Message

AMI Message Stop

TIBRVMSG:

TIBRVMSG_BOOL - "STOP" - "TRUE"TIBRVMSG_STRING-"INBOX"=

Table 18 Format of a Stop Message


INBOX TIBRVMSG_STRING The inbox address sent to the manager in the discovery message.

STOP TIBRVMSG_BOOL This value must be set to TRUE.


Unsolicited Message | 87

Unsolicited Message

An unsolicited message is sent by an application when it is to send information to its manager. If the manager is a TIBCO Hawk agent, these messages can be seen in the TIBCO Hawk Display or the AMI GUI when the method _onUnsolicitedMessage is called. (The _onUnsolicitedMessage method is supported by the TIBCO Hawk system and is not part of the AMI specification.) Unsolicited messages can only cause alerts to appear in the TIBCO Hawk Display when TIBCO Hawk agents using rules explicitly catch them and raise alerts.

Figure 28 Structure of an Unsolicited Message

AMI Message: Unsolicited Message

TIBRVMSG:

TIBRVMSG_STRING - "TEXT"TIBRVMSG_STRING-"TYPE"="INFO", "WARNING","ERROR"

TIBRVMSG_I32 - "ID"TIBRVMSG_STRING - "INBOX"

Table 19 Format of Unsolicited Message


TYPE TIBRVMSG_STRING The notification type. Must be one of INFO , WARNING , or ERROR .

TEXT TIBRVMSG_STRING The text description of the notification.

ID TIBRVMSG_I32 A user defined number that is typically used to assign a unique ID to each message. Use of this field in this way makes monitoring of notifications more efficient. This field must exist in the message even if its value has no significance.

INBOX TIBRVMSG_STRING The inbox address of the application’s management interface. Used to identify the source of this notification.


| 89

Chapter 5 Using the AMI WorkBench

The AMI WorkBench is a graphical user interface application used to test and communicate with a managed application, independently of the TIBCO Hawk Display. The AMI WorkBench acts as an AMI manager.

This chapter explains how to use the AMI WorkBench. The AMI WorkBench is nearly identical to the microagents window of the TIBCO Hawk Display, so familiarity with the TIBCO Hawk Display is recommended.

Topics

• About the AMI WorkBench, page 90

• Starting the AMI WorkBench, page 91

• The AMI WorkBench Main Window, page 92

• Invoking Methods, page 94

• Examining Error Messages, page 97

• Examining Unsolicited Messages, page 98


90 | Chapter 5 Using the AMI WorkBench

About the AMI WorkBench

The AMI WorkBench is a stand-alone utility that provides a separate graphical user interface (GUI) where you can test an AMI interface or to work with an application completely outside of the TIBCO Hawk monitoring system.

Setup of an AMI interface can be verified by calling methods from the AMI WorkBench before deploying the application. The AMI WorkBench serves as a manager for an application in much the same way as a TIBCO Hawk agent.

AMI WorkBench WindowThe AMI WorkBench has a single window (Figure 29) that is similar to the microagents window in the TIBCO Hawk Display.

In the AMI WorkBench window you can:

• Invoke methods of an application and observe the results.

• Review unsolicited messages sent by an application.

• Review error messages resulting from communication problems between an application and its manager (the AMI WorkBench).

Advantages of AMI WorkbenchThe TIBCO Hawk Display contains many tools that the AMI WorkBench does not include, including method subscription and network-wide query and action.

Use of the AMI WorkBench, instead of the TIBCO Hawk Display, for testing an AMI interface is recommended for the following reasons:

• The AMI WorkBench provides more debugging information, and more specific debugging information than is available using the TIBCO Hawk Display.

• By using the AMI WorkBench to test a managed application, there is no need to install, configure and run the full TIBCO Hawk system.

• Reviewing error messages and unsolicited messages from an application is accomplished more easily by the AMI WorkBench than by using the microagents window of the TIBCO Hawk Display.


Starting the AMI WorkBench | 91

Starting the AMI WorkBench

Start AMI WorkBench in Microsoft Windows Before you start AMI WorkBench make sure the HAWK_ROOT environment variable is set to the TIBCO Hawk installation directory. To start AMI WorkBench:

1. Run the batch file amiworkbench.bat in the C:\tibco\hawk\Samples\scripts directory.

2. Start the AMI WorkBench script with the following command-line option:-rvd_session <service> <network> <daemon>

The command-line option is configured in the same way as the one for the startagent , startdisplay and starthma scripts. For information on specifying local and remote TIBCO Rendezvous sessions, see the TIBCO Hawk Installation and Configuration.

Start AMI WorkBench in UNIXTo start AMI WorkBench:

1. Run the script amiworkbench in the $HAWK_ROOT/Samples/scripts directory.

2. Start the AMI WorkBench script with the following command-line option:-rvd_session <service> <network> <daemon>

The command-line option is configured in the same way as the one for the startagent , startdisplay and starthma scripts. For information on specifying local and remote TIBCO Rendezvous sessions, see the TIBCO Hawk Installation and Configuration.

Note: To successfully start the AMI WorkBench, the correct environmental variables must be set, either in the UNIX.cshrc file or in the Microsoft Windows System Properties window.



The AMI WorkBench Main Window

When you start the AMI WorkBench, the AMI WorkBench discovers any AMI-instrumented applications instrumented that use the same TIBCO Rendezvous service parameters. The AMI WorkBench main window (Figure 29) is similar to the microagents window in the TIBCO Hawk Display. This window shows all managed applications in the upper-left hand corner of the window. If you select an application in this list, its methods are listed in the area below it. If the method uses arguments, the upper-right hand corner of the window provides a place to enter them.

The help area at the bottom of the window displays the string returned in the HELP field that describes each method. If you choose an application but do not choose a method, the help area will display the contents of the HELP field that describes the application.

Figure 29 The AMI WorkBench Main Window


The AMI WorkBench Main Window | 93

The toolbar at the bottom of the main window has five buttons that allow you to perform various functions. These are: Subscribe, Unsolicited Messages, Error Messages, and Save. There are also radio buttons for Mode, Invoke, and Subscribe.

The Save button allows you to save discovered microagents to a file. One text file (for every microagent discovered) is created in the directory specified by the user. The name of the text file is the same as the microagent’s name. The text file contains information about all methods, their type, arguments, and return fields.

The Subscribe button allows you to subscribe to any IMPACT_INFO or IMPACT_ACTION_INFO method. This option works in a similar manner to the Invoke/Subscribe option of the Get Microagents window in the TIBCO Hawk display.

Unsolicited Msgs and Error Msgs display either unsolicited messages returned by a microagent or error messages messages.



Invoking Methods

To invoke a method of an AMI-instrumented application, perform the following steps:

1. Select the application in the list of instrumented applications.

2. Choose the method in the list below the list of applications.

3. Enter any arguments required.

4. Click Invoke Method.

The response of the AMI WorkBench is as follows.

If the application was found,and the method invocation was successful,

and at least one result was returned, then the invocation results window appears showing the result of the method (Figure 30).

If the method invocation was successful but returned no result,then a simple dialog appears telling you that the method invocation was successful (Figure 31).

If the application was found but the method invocation was not successful,If the problem was with processing of the method call by the application,

then a dialog appears returning the string the application returned in the ERROR field (Figure 32).

If the problem was that the message returned from the method did notmatch with the description given for that method in _describeMethods ,

then a dialog appearsgiving an explanation of what was expected and what was found (Figure 33).

If the application was not found,then after a time-out period a dialog appears telling you that the application did not respond (Figure 34).


Invoking Methods | 95

Figure 30 Result of a Successful Method Invocation That Returns a Table of Data

Figure 31 Result of a Successful Method Invocation That Returns No Data

Figure 32 Result of a Failed Method Invocation—Application Returned an Error

Figure 33 Result of a Failed Method Invocation—Discrepancy between Described and



Implemented Methods

Figure 34 Result of a Failed Method Invocation —Application Did Not Respond and the Invocation Timed Out


Examining Error Messages | 97

Examining Error Messages

When errors in communication occur while using the required AMI methods (_describeMethods and _heartbeat), use the Error and Warning Messages window (Figure 35) to obtain details.

To bring up the window, click Error Msgs. When a new error occurs, this button turn red to notify you that a new error has been reported. The red color disappear after the Error & Warning Messages window is accessed.

Figure 35 The Error Messages Window



Examining Unsolicited Messages

When an instrumented application sends an unsolicited message to its manager (the AMI WorkBench), the message appears in the Unsolicited Messages window (Figure 36).

Figure 36 The Unsolicited Messages Window

To bring up this window, click Unsolicited Msgs. As with the Error and Warning Messages window, when the AMI WorkBench receives a new unsolicited message, Unsolicited Msgs button will turn red until the unsolicited messages window is accessed.


| 99

Chapter 6 Security Framework

The TIBCO Hawk product currently supports the ability to “plug-in” an authorization module. The TIBCO Hawk Display uses the plug-in module to create identification objects. The TIBCO Hawk agent guarantees that every request is authorized before execution by invoking the appropriate plug-in method.

The techniques used to address authentication, authorization, integrity, and privacy with regard to messaging and communication channels are varied. It is the goal of the framework to be completely independent of these techniques so that a plug-in is possible regardless of the tools and techniques chosen for implementation.

Implementation of the Certified Class and Trusted Class security models is discussed in TIBCO Hawk Installation and Configuration.

Topics

• TIBCO Hawk Security Concepts, page 100

• Implementing a Security Policy, page 103

• HsException, page 105

• HsIdentifier, page 107

• HsOperation, page 109

• HsNode, page 111

• HsNodeOperation, page 114

• HsGroupOperation, page 117

• HsPackedOperation, page 120

• HsUnpackedOperation, page 122

• HsConsoleInterface, page 125

• HsAgentInterface, page 131

• Sample Code, page 137


100 | Chapter 6 Security Framework

TIBCO Hawk Security Concepts

A secure environment addresses concerns of data authentication, authorization, privacy, and integrity.

AuthenticationData authentication is the practice of determining that an entity (such a person or system process) is who it claims to be. This verification can be performed through use of a shared secret system, such as requiring a password, or through certificates and digital signatures.

Authentication involves the following interactions.

1. The entity that is to identify itself to a verifying entity provides an identifier to that verifying entity. The identifier specifies that the originating entity has a particular identity.

2. The verifying entity then receives the identifier from the entity. It uses the verifier to check the authenticity of the entity’s claim. In some instances, the verifying entity can be its own verifier.

3. The verifier makes sure that an entity is who it claims it is. This process may or may not involve communication with the entity making the claim.

The verification can involve different levels of authentication.

Identity Only

In identity-only authentication, the system does not verify that the entity is who it claims it is, but does pass the entity’s identifier to other parts of the system. This is the lowest level of authentication, and is useful where costs of a more secure authentication system preclude higher degrees of security, but identity is still important. This sort of authentication is useful where non-sensitive data is involved.

Shared Secret

Shared secret authentication is where each entity has a secret, such as a password, that is shared with the authentication system. Proof that the entity holds the secret can take one of the following forms.

• The secret is sent from the entity to the verifier. Web browsers using the basic authentication web paradigm use this method. It is not very secure, as it is possible to impersonate the entity. More security can be added by encrypting the conversation.


TIBCO Hawk Security Concepts | 101

• The secret is used to encrypt a commonly-known piece of data. The encrypted data is then sent to the authentication system, which then verifies the identity of the sender by performing its own data encryption and comparing the result with the sender’s data.

• A “challenge-response” protocol is used, wherein the verifier provides a piece of randomly-generated data, which the sending entity encrypts using the shared secret. The entity sends back the encrypted data, which the verifier then compares with its own version. If they match, the verifier accepts that the entity is who it claims it is.

CertificatesDigital certificates are a means whereby an entity has a public-private key pair, and registers the public key with a Certificate Authority. The infrastructure required for a public key system is referred to as a Public Key Infrastructure (PKI), of which the third-party Certificate Authority is a part. The Certificate Authority issues a certificate, containing information about the entity and the entity’s public key, and signs it.

To provide authentication of identity, the authentication system challenges the entity in a similar manner to the challenge-response protocol. The entity signs the challenge using its private key, and the system verifies this signature by using the entity’s public key.

Further information concerning security certificates can be found in TIBCO Hawk Installation and Configuration.



Authorization

Authorization is generally concerned with operations on which to grant permissions. Sometimes these permissions are determined by work groups or other concerns. Use of tickets, such as tibrv.tkt , is an example of authorization. A ticket is used for authentication and authorization in lieu of other credentials. In other cases, the issue is whether a certain operation can be performed on a specified system, or by a specified user.

Data Privacy and IntegrityData privacy and integrity use encryption techniques to make sure unauthorized entities can’t see or modify sensitive data. These techniques are also used when a principal needs to prove it originated a message. Encryption can either use the same key to encrypt and decrypt a message, or use a public-private key pair, where encrypted data using the public key can only be decrypted using the private key, and vice versa.

Data integrity is maintained by using one-way hash functions. These functions generate fixed-length output from input. When sending a message, the sender runs the one-way hash function on the message, encrypts the resulting hash value, and sends the resulting message identification code (MIC) along with the message. The recipient runs the same function on the message, decrypts the MIC, and sees if the results match. A match indicates that the message has not been tampered with.

Considerations for the TIBCO Hawk SystemThe security provisions of the TIBCO Hawk monitoring system are consistent with its scalable distributed architecture. While a user is not required to trade off scalability for security, the flexibility of the security framework allows choosing a loss of scalability in return for high degrees of security. It also provides a modular mechanism for addressing security, in which the TIBCO Hawk agent can delegate responsibility to the security module, through the interfaces of the security framework. Because every user has unique security needs, security is presented as an open framework. You can develop methods that grant or deny permissions to meet your requirements.


Implementing a Security Policy | 103

Implementing a Security Policy

The TIBCO Hawk software provides a security framework that you can adapt to your own security needs. To use a security policy, you create a Java class that implements the security interface.

Because every system has unique security needs, the security policy provides an open framework for security implementation, rather than a standardized security policy. You can develop methods to grant or deny permissions based on your needs. A Java interface is provided.

Creating a Java Security ClassThe TIBCO Hawk security system must be implemented as a Java class, though you may choose to make this class a simple wrapper that uses the Java Native Interface (JNI) to call other security methods in a C or C++ library. The Java class must implement the HsConsoleInterface and HsAgentInterface , which are included with the TIBCO Hawk distribution.

The name of the Java class file for security must be passed to the TIBCO Hawk Display and the TIBCO Hawk agent as a command-line argument.

Once both of these processes have been started using this argument, the security policy is in force.

Framework ProtocolThe security framework supports an agent and a client-side protocol, as shown below. The client side supports the creation of an identifying object (createid() in the diagram) and the transformation of the message (pack() in the diagram).

The agent side supports inverse operations for restoring the message’s original format (unpack()) and validating the identifying object (validateid()).



Figure 37 Security Framework Model

Security ObjectsWhile a sample security framework plug-in is provided later in this section, users may prefer to write their own security framework implementation. Plug-ins for the security framework are created using the classes listed here. The prefix Hs designates the object as part of the TIBCO Hawk Security Framework.

The following pages provide security classes you can use to create plug-ins.

createId()validateId()

pack() unpack()

Agent

Ope

ratio

n

Ope

ratio

n

Client

Ope

ratio

n

Ope

ratio

n

mes

sage

mes

sage

Iden

tifie

r

Iden

tifie

r

TIBCO RendezvousTIBCO Rendezvous


HsException | 105

HsException Class

Declaration public class HsException extends Exception ;

Purpose TIBCO Hawk security exception object.

Remarks The HsException object is thrown to indicate that a failure has occurred during the processing of a request by the security framework or plug-in. The exception text provides the exact cause of the failure.

MemberSummary

Name Description Page

HsException.HsException() Constructor. 106



HsException.HsException()Constructor

Declaration public HsException(String msg)

Purpose Creates an HsException instance.

Parameters Name Description

msg Message to encapsulate in this HsException .


HsIdentifier | 107

HsIdentifierClass

Declaration public class HsIdentifier

Purpose TIBCO Hawk security identifier object.

Remarks The HsIdentifier object acts as an envelope for transporting an opaque buffer containing information about the identity of the originator. The security framework makes no attempt to interpret the contents.

Data Members public byte[] contents;

MemberSummary


HsIdentifier.HsIdentifier() Constructor. 108



HsIdentifier.HsIdentifier()Constructor

Declaration public HsIdentifier(byte[] opaque) throws HsFrameworkException;

Purpose Creates an HsIdentifier which can then be used to transport the opaque buffer passed in as an argument.


opaque Buffer containing information about the identity of the originator.


HsOperation | 109

HsOperationClass

Declaration public class HsOperation

Purpose TIBCO Hawk security request object.

The HsOperation object contains the request itself and also information about the request.

Remarks The HsOperation object contains a request and also information about the request. The object acts as an envelope for transporting an opaque buffer containing the request. The plug-in should not attempt to interpret the contents. You can obtain information about the request by invoking methods.

The class has two subclasses, HsNodeOperation and HsGroupOperation , which are passed to the plug-in by the framework.

Data Members public static final int VOID = 0;public static final int INFO = 1;public static final int ACTION = 2;public static final int ACTION_INFO = 3;



HsOperation.HsOperation()Constructor

Declaration public HsOperation(byte[] operation) throws HsFrameworkException;

Purpose Encapsulates a request.


opaque Buffer containing the request.


HsNode | 111

HsNodeClass

Declaration public class HsNode

Purpose TIBCO Hawk security node identifier. The HsNode object uniquely identifies a TIBCO Hawk agent. The agent name, along with the DNS name and the TIBCO Hawk domain, uniquely identify any agent on the network.

MemberSummary


HsNode.HsNode() Constructor. 112

HsNode Accessors Accessors: agent()

dns()

domain()

113



HsNode.HsNode()Constructor

Declaration public HsNode(String agent, String dns, String domain) throws HsFrameworkException;


agent Name of the TIBCO Hawk agent.

dns DNS entry name.

domain TIBCO Hawk domain name.


HsNode Accessors | 113

HsNode AccessorsAccessors

Declaration public String agent();public String dns();public String domain();

Purpose Accessors for this HsNode instance.

Name Description

agent() Retrieves the TIBCO Hawk agent associated with this node.

dns() Retrieves the DNS entry associated with this node.

domain() Retrieves the domain associated with this node.



HsNodeOperationClass

Declaration public class HsNodeOperation extends HsOperation

Purpose TIBCO Hawk security message request object. The HsNodeOperation object extends HsOperation and represents a point-to-point invocation request. Additional information about the type of the request can be obtained by invoking methods on the object.

MemberSummary

Name Description

HsNodeOperation.HsNodeOperation() Constructor.

HsNodeOperation Accessors Accessors. type()

microagent()

method()

node()


HsNodeOperation.HsNodeOperation() | 115

HsNodeOperation.HsNodeOperation()Constructor

Declaration public HsNodeOperation(HsNode node, String method, int type, byte[] operation)

throws HsFrameworkException;

Purpose Creates instances of HsNodeOperation to encapsulate a point-to-point invocation request.

Parameters Parameter Description

node Name of security node.

method Method to be invoked.

type Type of request. One of HsOperation.INFO , HsOperation.ACTION , HsOperation.ACTION_INFO .

operation Operation to be encapsulated by this instance.



HsNodeOperation AccessorsAccessors

Declaration public int type();

String microagent();

String method();

HsNode node();

Purpose Retrieves information about this HsNodeOperation instance.

Method Description

type() Retrieves the type of request. One of HsOperation.INFO , HsOperation.ACTION , HsOperation.ACTION_INFO .

microagent() Retrieves the name of the associated microagent.

method() Retrieves the method.

node() Retrieves the node.


HsGroupOperation | 117

HsGroupOperationClass

Declaration public class HsGroupOperation extends HsOperation

Purpose HsGroupOperation extends HsOperation and represents a broadcast invocation request. Additional information about the type of the request can be obtained by invoking methods on the object.

MemberSummary

Name Description

HsGroupOperation.HsGroupOperation() Constructor.

HsGroupOperation Accessors Accessors. type()

microagent()

method()

node()



HsGroupOperation.HsGroupOperation()Constructor

Declaration public HsGroupOperation(HsNode[] nodes, String method, int type, byte[] operation)


Purpose Creates instances of HsNodeOperation to encapsulate a point-to-point invocation request.

Parameters Parameter Description

nodes Array of security node.

method Method to be invoked.

type Type of request. One of HsOperation.INFO , HsOperation.ACTION , HsOperation.ACTION_INFO .

operation Operation to be encapsulated by this instance.


HsGroupOperation Accessors | 119

HsGroupOperation AccessorsAccessors

Declaration public int type();

String microagent();

String method();

HsNodes[] nodes();

Purpose Retrieves information about this HsNodeOperation instance.

Method Description

type() Retrieves the type of request. One of HsOperation.INFO , HsOperation.ACTION , HsOperation.ACTION_INFO .

microagent() Retrieves the name of the associated microagent.

method() Retrieves the method.

node() Retrieves the array of nodes.



HsPackedOperationClass

Declaration public class HsPackedOperation throws HsFrameworkException

Purpose Class for encapsulating TIBCO Hawk security packed requests. Instances of this class are used by the framework to transport the opaque object representing the transformed request. No attempt to interpret the contents of the request is made by the framework.

Data Members public byte[] contents;

MemberSummary

Name Description

HsPackedOperation.HsPackedOperation() Constructor.


HsPackedOperation.HsPackedOperation() | 121

HsPackedOperation.HsPackedOperation()Constructor

Declaration public HsPackedOperation(byte[] buffer) throws HsFrameworkException;

Parameter Parameter Description

buffer Buffer containing the request to encapsulated.



HsUnpackedOperationClass

Declaration private class HsUnpackedOperation

Purpose TIBCO Hawk security authenticated request object. The HsUnpackedOperation object contains information about the identity of the originator of the request as well as the actual request. An object of this type is returned by the HsAgentInterface.unpack() method after it has reversed the transformation performed by the HsConsoleInterface.pack() method.

MemberSummary

See Also HsAgentInterface.unpack() , page 135HsConsoleInterface.pack() , page 130


HsUnpackedOperation.HsUnpackedOperation()

Constructor 123

HsUnpackedOperation Accessors Accessors. id()

operation()

124


HsUnpackedOperation.HsUnpackedOperation() | 123

HsUnpackedOperation.HsUnpackedOperation()Constructor

Declaration public HsUnpackedOperation(HsIdentifier id,HsOperation operation)



id ID of the originator of the request.

operation Request to encapsulate.



HsUnpackedOperation AccessorsAccessors

Declaration public HsIdentifier id();

public HsOperation operation();

Purpose Retrieve information about this instance.

Method Description

id() Retrieves the identity of the request originator.

operation() Retrieves the requested operation.


HsConsoleInterface | 125

HsConsoleInterfaceInterface

Declaration public interface HsConsoleInterface

Purpose The console interface implements a Java public interface.

MethodSummary

Method Description Page

HsConsoleInterface.describe() Describes the plug-in. 126

HsConsoleInterface.initialize() Performs plug-in initialization. 127

HsConsoleInterface.shutdown() Halts functioning of plug-in. 128

HsConsoleInterface.createId() Identifies message originator. 129

HsConsoleInterface.pack() Transforms message for transmission.

130



HsConsoleInterface.describe()Method

Declaration String describe();

Purpose This method furnishes a textual description of the plug-in.


HsConsoleInterface.initialize() | 127

HsConsoleInterface.initialize()Method

Declaration String initialize(int context) throws HsException;

Purpose Initializes the plug-in.

Remarks The initialize() method is called once (until a subsequent call to shutdown() is successful) to perform any initialization necessary for the functioning of the plug-in. The call is in effect until a subsequent call to shutdown() is successful.


context Context from which this initialization is being invoked. Possible contexts are:

HsConsoleInterface.WINDOW—Indicates an interactive windowing environment. It is possible to perform interactive activities from this context.

HsConsoleInterface.CONSOLE—Indicates an interactive console environment. It is also possible to perform interactive command line activities from this context.

HsConsoleInterface.DAEMON—Indicates a non-interactive batch or background process. It is not possible to perform interactive activities from this context.



HsConsoleInterface.shutdown()Method

Declaration void shutdown (int context) throws HsException;

Purpose Halts the plug-in.

Remarks The shutdown() method is called once (until a subsequent call to initialize() is successful) to halt the functioning of the plug-in. The plug-in should assume that any security and/or identity verification previously performed is no longer valid and must be performed again before resuming normal operation.


context Context from which this initialization is being invoked. Possible contexts are:

HsConsoleInterface.WINDOW—Indicates an interactive windowing environment. It is possible to perform interactive activities from this context.

HsConsoleInterface.CONSOLE—Indicates an interactive console environment. It is also possible to perform interactive command line activities from this context.

HsConsoleInterface.DAEMON—Indicates a non-interactive batch or background process. It is not possible to perform interactive activities from this context.


HsConsoleInterface.createId() | 129

HsConsoleInterface.createId()Method

Declaration HsIdentifier createId (HsOperation operation) throws HsException;

Purpose Provides information needed to identify the originator of the message. This information is encapsulated in a byte array and is intended to aid in the transformation of the message by the pack() method. The returning of this information is encapsulated in createId() and the results passed to the pack() method for three reasons. First, the knowledge needed to obtain the information is not related to the message transformation process. Second, the invoker of the plug-in may need to pack multiple messages from the same originator. Third, it makes the plug-in inherently thread-safe.


operation Operation for which to create an ID.



HsConsoleInterface.pack()Method

Declaration HsPackedOperation pack (HsIdentifier id, HsOperation operation) throws HsException;

Purpose The pack() method supports message transformation.

Remarks The ability to transform a message is a powerful capability that enables encryption and integrity techniques to be employed. As a side effect of these techniques, it is often possible to also identify the origin of the message. The pack() method is invoked on all messages prior to transmitting. If the pack() method returns null, the message will not be sent.


id ID.

operation Operation to pack.


HsAgentInterface | 131

HsAgentInterfaceInterface

Declaration public interface HsAgentInterface

Purpose Creates constructor for public class for the TIBCO Hawk agent.

MethodSummary

Method Description Page

HsAgentInterface.describe() Provides a textual description of the plug-in.

132

HsAgentInterface.initialize() Performs plug-in initialization 133

HsAgentInterface.shutdown() Halts functioning of plug-in. 134

HsAgentInterface.unpack() Transforms transmitted message.

135

HsAgentInterface.validateId() Validates identifier number. 136



HsAgentInterface.describe()Method

Declaration String describe();

Purpose Provides a textual description of the plug-in.


HsAgentInterface.initialize() | 133

HsAgentInterface.initialize()Method

Declaration void initialize() throws HsException;

Purpose Initializes the plug-in.

Remarks The initialize() method is called once to perform any initialization necessary for the functioning of the plug-in.



HsAgentInterface.shutdown()Method

Declaration void shutdown() throws HsException;

Purpose Halts the plug-in.

Remarks The shutdown() method is called once to halt the functioning of the plug-in. The call is in effect until a subsequent call to initialize() is successful. The plug-in should assume that any security and/or identity verification previously performed is no longer valid and must be performed again before resuming normal operation.


HsAgentInterface.unpack() | 135

HsAgentInterface.unpack()Method

Declaration HsUnpackedOperation unpack (HsPackedOperation operation) throws HsException;

Purpose The unpack() method supports message transformation.

Remarks This method enables decryption and integrity techniques to be employed. The method will be invoked prior to validating messages.



HsAgentInterface.validateId()Method

Declaration boolean validateId(HsIdentifier id, HsOperation operation) throws HsException;

Purpose The validateId() method provides a mechanism for authorizing requests made of the agent.


Sample Code | 137

Sample Code

The following sample code shows an example of a security policy class file in Java.

/* * Copyright (c) 1997, 1998 TIBCO Software, Inc. All Rights Reserved. * * This software is the confidential and proprietary information of * TIBCO Software Inc. */package COM.TIBCO.hawk.security.test;

import java.lang.*;import java.io.*;

import COM.TIBCO.hawk.console.security.*;

public class Test implements HsConsoleInterface, HsAgentInterface {

public void Test() {System.out.println("PLUGIN: Test.constructor()");

}

public void initialize() throws HsException {System.out.println("PLUGIN: Test.initialize()");

}

public void shutdown() throws HsException {System.out.println("PLUGIN: Test.shutdown()");

}

public String initialize(int context) throws HsException {System.out.println("PLUGIN: Test.initialize(" + context +

")");

return null;}

public void shutdown(int context) throws HsException {System.out.println("PLUGIN: Test.shutdown(" + context +

")");}

public HsIdentifier createId(HsOperation operation) throws HsException

{if (operation instanceof HsNodeOperation)

System.out.println("PLUGIN: createId(" + ((HsNodeOperation)operation).microagent() + ":" + ((HsNodeOperation)operation).method() + ")");

else if (operation instanceof HsGroupOperation)System.out.println("PLUGIN: createId(" +



((HsGroupOperation)operation).microagent() + ":" +

((HsGroupOperation)operation).method() + ")");else

System.out.println("PLUGIN: Unknown request");

HsIdentifier id = null; try {

String name = new String("Test Plug-In"); id = new HsIdentifier(name.getBytes()); } catch (HsFrameworkException hsfe) { throw new HsException(hsfe.toString()); }

return(id);}

public HsPackedOperation pack(HsIdentifier id, HsOperation operation)

throws HsException{

if (operation instanceof HsNodeOperation) System.out.println(

"PLUGIN: pack("+ new String(id.contents)+ "," +

((HsNodeOperation)operation).microagent() + ":" + ((HsNodeOperation)operation).method() +

")");else if (operation instanceof HsGroupOperation)

System.out.println("PLUGIN: pack(" + new String(id.contents)+ "," +

((HsGroupOperation)operation).microagent() + ":" +

((HsGroupOperation)operation).method() + ")");else

System.out.println("PLUGIN: Unknown request");

TestOperation trustme = new TestOperation(id.contents, operation.contents);

byte[] packed = null;try {

ByteArrayOutputStream buffer = new ByteArrayOutputStream();

ObjectOutputStream out = new ObjectOutputStream(buffer);

out.writeObject(trustme);out.flush();out.close();

packed = buffer.toByteArray();

} catch (IOException ioe) {}

HsPackedOperation packedOperation = null; try {


Sample Code | 139

packedOperation = new HsPackedOperation(packed); } catch (HsFrameworkException hsfe) { throw new HsException(hsfe.toString()); }

return (packedOperation);}

public HsUnpackedOperation unpack(HsPackedOperation operation) throws HsException

{System.out.println("PLUGIN: unpack(operation)");

TestOperation trustme = null;try {

ByteArrayInputStream buffer = new ByteArrayInputStream(operation.contents);

ObjectInputStream in = new ObjectInputStream(buffer);

trustme = (TestOperation)in.readObject();in.close();

} catch (ClassNotFoundException cnfe) {throw new HsException(cnfe.toString());

} catch (IOException ioe) {throw new HsException(ioe.toString());

}

HsUnpackedOperation unpacked = null; try { unpacked = new HsUnpackedOperation (new HsIdentifier(trustme.id),new HsOperation(trustme.operation)); } catch (HsFrameworkException hsfe) { throw new HsException(hsfe.toString()); }

return unpacked;}

public boolean validateId(HsIdentifier id, HsOperation operation)

{if (operation instanceof HsNodeOperation) System.out.println("PLUGIN: validateId("+new

String(id.contents)+","+ ((HsNodeOperation)operation).microagent() + ":" + ((HsNodeOperation)operation).method() + ")");

else if (operation instanceof HsGroupOperation) System.out.println("PLUGIN: validateId("+new

String(id.contents)+","+ ((HsGroupOperation)operation).microagent() + ":"

+ ((HsGroupOperation)operation).method() + ")");

elseSystem.out.println("PLUGIN: Unknown request");

String name = new String(id.contents);



if (name.equals("Test Plug-In"))return(true);

elsereturn(false);

}

public String describe() {System.out.println("PLUGIN: Test.describe()");

return(new String("TIBCO Hawk Test security model."));}

}


| 141

Chapter 7 AMI Programming Examples

The TIBCO Hawk system furnishes sample files in C, C++, and Java with the release distribution.

You can write AMI applications in any language supported by the TIBCO Rendezvous system.

Topics

• Sample Directories, page 142

• AMI Example In Java, page 143


142 | Chapter 7 AMI Programming Examples

Sample Directories

The <TIBCO Hawk Installation directory>\samples\ami.api (Microsoft Windows) and $HAWK_ROOT/samples/ami.api (UNIX) directories provide samples of API programs for C, C++, and Java, each under an appropriate directory. For instructions on installing sample programs, refer to TIBCO Hawk Installation and Configuration.

An excellent way to become familiar with the AMI system is to open one of the examples in your development environment and follow the program in your debugger. Examine all of the messages created and received, and drill down into the nested messages to see how they work. Place breakpoints on all the places where messages arrive and are dispatched, and send messages from the TIBCO Hawk Display.

We do suggest that you read the concepts chapter of this programmer’s guide and the book TIBCO Rendezvous Concepts.


AMI Example In Java | 143

AMI Example In Java

The Java AMI example provided is the Spot program. You can find the Java files SpotAmi.java (the AMI object) and Spot.java (the frame object) in the samples directory.

The <TIBCO Hawk Installation directory>\samples\ami.api (Microsoft Windows) and $HAWK_ROOT/samples/ami.api directories provide samples of API programs.


144 | Chapter 7 AMI Programming Examples


| 145

Appendix A Frequently Asked Questions

This appendix presents answers to some common questions about the TIBCO Hawk Application Management Interface.

How can I build a rule that takes an action when an instrumented application dies?

Use the self:getMicroagentInfo method, giving the name the application specifies in its AMI initialization as an argument. Test for a return value of zero.

Also, if the application is not a Java application, you can use the microagent method process:getInstanceCount (UNIX) or performance:ProcessCount (Microsoft Windows), giving the name of the process as an argument. Test for a return value of zero.

Can I put off the discovery of my interface until my application does some initialization?

Interface discovery and method description can only take place after the application has either sent out its announcement message or subscribed to the manager's discovery message. If you need to delay interface discovery, don't take these steps until you are ready.

Can I force the rediscovery of methods after startup?

The only way to force rediscovery of methods is to effectively create a new AMI interface. This can be simulated by canceling your AMI subscriptions and repeating the initialization sequence. This involves generating a new inbox, re-subscribing to the discovery message, and re-sending the announcement message.

Why doesn’t the TIBCO Hawk agent or AMI WorkBench respond to my support of _startRepeatingMethod?

The current version of the AMI protocol does not implement this method.

Why does the AMI WorkBench give me an error when I describe the


146 | Appendix A Frequently Asked Questions

_describeMethods and _heartbeat methods?

These methods are required and therefore need not be described in the _describeMethods message.

I have implemented a simple AMI interface to my application. The TIBCO Hawk Display won’t show it in my microagents list. What should I do?

First, try interacting with your application using the AMI WorkBench (see Using the AMI WorkBench on page 89). This will give you more complete debugging messages so that you can determine what is wrong.

Second, check these items:

— Did you properly set up a TIBCO Rendezvous session in your AMI interface? Consult the AMI code examples and your TIBCO Rendezvous documentation for help.

— Did you use the same TIBCO Rendezvous session parameters in your TIBCO Hawk agent and your AMI interface? For more information on setting up sessions to monitor applications instrumented with AMI, see the TIBCO Hawk Installation and Administrator’s Guide.

— Is the CONTEXT field missing in any of your messages? When the manager invokes the _describeMethods method, the manager sends a CONTEXT field in the request message. The application must include a CONTEXT field in its reply, and that CONTEXT must has the same value as the CONTEXT field sent in the request.

When I call a method of my instrumented application, I get an error. Why is this?

Check that the message descriptions in your _describeMethods return message matches up exactly with the messages returned by your methods. If the identifiers do not match up, an error will result.

Use the AMI WorkBench to interact with your application for preliminary testing. Examine the error messages you receive when you call the method.

I cannot get the AMI WorkBench script to execute.

Check your environmental variables. HAWK_ROOT, RV_ROOT, and JRE_ROOT must all be set to reflect the current installation directory.

If you use TIBCO Rendezvous with other applications, you already have non-flavored tickets. Make sure that the directory <TIBCO Rendezvous home directory>/bin comes before the directory <TIBCO Hawk home directory>/bin in


Frequently Asked Questions | 147

your PATH so that the non-flavored license ticket is used when the TIBCO Hawk agent processes are started.

I get errors on my Microsoft Windows system, despite trying the approaches listed above.

Please note that any changes made to the Microsoft Windows environment and registry requires the machine to be rebooted, otherwise none of the changes will propagate to the Microsoft Windows Services. Reboot and try the operation again.


148 | Appendix A Frequently Asked Questions


| 149

Index

Symbols

_describemethodsinvocation of 44

_heartbeatinvocation of 44

_startRepeatingMethod 145_startrepeatingmethod

invocation of 45_stoprepeatingmethod

invocation of 46

A

about the AMI WorkBench 90advantages of AMI Workbench 90agent through a local daemon

connecting to a remote 19agent through a remote daemon

connecting to a remote 19agents

daemons and 13AMI

and TIBCO Hawk security 27application looks like a microagent 11basics 9concepts 7conversation 20

messages sent during an 52

Three stages of 20discovery when the application starts first 22discovery when the manager starts first 21has three stages 11has two participants 4, 10heartbeat request 24initialization 34introduction 1method description 23method invocation 24methods 25

example of planning 29participants 17

connecting 18programming

guidelines for 31protocol 9TIBCO Hawk system 11TIBCO Rendezvous concepts used in 13TIBCO Rendezvous messaging 10

AMI and TIBCO Hawk security 27AMI basics 9AMI conversation 20AMI example In Java 143AMI initialization 34AMI methods 25AMI participants 17AMI sessions 10AMI TIBCO Rendezvous messaging 4AMI uses TIBCO Rendezvous messaging 10AMI WorkBench 145AMI WorkBench main window 92AMI WorkBench window 90announcement message 53

structure 53application looks like a microagent

AMI 11application messages

unsolicited 26


150 | Index

application starts firstAMI discovery when the 22if the 21

argumentsstructure of a parameter list message when used to

send 72authentication 100authorization 102

B

basicsAMI 9

C

callback functions 15certificates 101changes from the previous release xivconcepts

AMI 7TIBCO Rendezvous 13

connecting AMI participants 18connecting to a remote agent through a local

daemon 19connecting to a remote agent through a remote

daemon 19considerations for the TIBCO Hawk system 102conversation

AMI 20messages sent during an AMI 52three stages of AMI 20

CreateId () 129creating a Java security class 103customer support xix

D

daemonconnecting to a remote agent through a local 19connecting to a remote agent through a remote 19

daemons and agents 13data privacy and integrity 102described and implemented methods 95describing methods 22description

AMI method 23method 36

description reply messagemethod 58structure

method 58description request message

method 57structure

method 57descriptor message

method 60parameter 66structure

method 60parameter 66

descriptors list messageparameter 63structure

parameter 64discovering instrumented applications

starting the AMI WorkBench and 91discovery

Interface 35discovery phase 21discovery request and reply messages 55

structure of 55discovery when the application starts first

AMI 22discovery when the manager starts first

AMI 21


Index | 151

E

error messagesexamining 97

error messages window 97event managers 16examining error messages 97examining unsolicited messages 98example of planning AMI methods 29, 29example of returning a table of data 41exception, Java 95

F

features of the TIBCO Hawk application management interface 5

first AMI Phasediscovering the application 21

fixed subject names for messages 14framework protocol 103functions

callback 15

G

guidelines for AMI programming 31

H

heartbeat reply messagestructure 75

heartbeat requestAMI 24

heartbeat request and reply messages 75heartbeat request message

structure 75HsAgentInterface 131HsConsoleInterface 125HsException 105

HsGroupOperation 115, 118HsIdentifier 107HsNode 111HsOperation 109HsPackedOperation 120HsUnpackedOperation 122

I

implementation of an authorization module 104implementing a security policy 103inclusion of operating systems not supported by

TIBCO Hawk software 9initialization

AMI 34initialize() 133instrumented application 11

planning 28instrumented applications and flavoring 50interface discovery 35introduction

AMI 1introduction to the messages 52invocation

AMI method 24method 42

Invocation of _describemethods 44Invocation of _heartbeat 44Invocation of _startrepeatingmethod 45Invocation of _stoprepeatingmethod 46invocation of optional reserved methods

method 45invocation of required reserved methods

method 44invocation of reserved methods

method 44invocation of user-defined methods

method 47invocation reply message

method 70structure

method 70


152 | Index

invocation request messagemethod 68repeating method 77stop repeating method 79structure

method 68repeating method 77, 77

Invoking methods 94

J

Java exception 95

L

list messageparameter 72parameter descriptors 63structure

parameter descriptors 64local daemon

connecting to a remote agent through a 19

M

manager starts firstAMI discovery 21if the 21

managersevent 16

messageannouncement 53method description reply 58method description request 57method descriptor 60method invocation reply 70method invocation request 68parameter descriptor 66parameter descriptor list 63parameter list 72repeating method invocation request 77stop repeating method invocation request 79structure

announcement 53heartbeat reply 75heartbeat request 75method description reply 58method description request 57method descriptor 60method invocation reply 70method invocation request 68parameter descriptor 66parameter descriptor list 64repeating method invocation request 77, 77unsolicited 87

unsolicited 87message sending

unsolicited 49messages

discovery request and reply 55examining error 97examining unsolicited 98heartbeat request and reply 75introduction to the 52self-describing 14structure of discovery request and reply 55structure of stop repeating method request and

reply 79unsolicited application 26

messages sent during an AMI conversation 52messages window

error 97unsolicited 98

messagingAMI uses TIBCO Rendezvous 4, 10


Index | 153

method description 36, 36AMI 23

method description reply message 58structure 58

method description request message 57, 57structure 57

method descriptor message 60structure 60

method invocation 42AMI 24

method invocation of optional reserved methods 45method invocation of required reserved methods 44method invocation of reserved methods 44method invocation of user-defined methods 47method invocation reply message 70

structure 70method invocation request message 68

repeating 77stop repeating 79structure 68

repeating 77, 77methods

AMI 25describing 22example of planning AMI 29invoking 94method invocation of optional reserved 45method invocation of required reserved 44method invocation of reserved 44method invocation of user-defined 47optional repeating 25required 25user-defined 25

microagentAMI application looks like a 11

monitoring an instrumented application through the TIBCO Hawk Display 18

N

no data 95no response 96

O

optional methods 25optional repeating methods 25optional reserved methods

method invocation of 45

P

pack () 130parameter descriptor list message 63

structure 64parameter descriptor message 66

structure 66parameter list message 72parameter list message when used to send arguments

structure 72parameter list message when used to send results

structure 72participants

AMI 17AMI has two 10connecting AMI 18

planning AMI methodsexample of 29

planning instrumented application 28programming

guidelines for AMI 31programming samples 142protocol

AMI is a 9

R

remote agent through a local daemonconnecting to a 19

remote agent through a remote daemonconnecting to a 19

remote daemonconnecting to a remote agent through a 19


154 | Index

repeating method invocation request message 77stop 79structure 77, 77

repeating methodsoptional 25

reply messagemethod description 58method invocation 70structure

heartbeat 75method description 58method invocation 70

reply messagesheartbeat request and 75structure of discovery request and 55structure of stop repeating method request and 79

request and reply messagesheartbeat 75structure of discovery 55structure of stop repeating method 79

request messagemethod description 57method invocation 68repeating method invocation 77stop repeating method invocation 79structure

heartbeat 75method description 57method invocation 68repeating method invocation 77, 77

required methods 25required reserved methods

method invocation of 44reserved methods

method invocation of 44method invocation of optional 45method invocation of required 44

response, none 96results

structure of a parameter list message when used to send 72

results in the form of tablesreturning 74

returned Item description 37

returning a table of dataexample of 41

returning results in the form of tables 74

S

sample code 137second AMI phase

describing methods 22security

AMI and TIBCO Hawk 27security objects 104self-describing messages 14sending

Unsolicited message 49sessions 13shutdown() 134stages

AMI has three 11stages of AMI conversation 20, 20start AMI WorkBench in Microsoft Windows 91starting the AMI WorkBench 91stop repeating method invocation request message 79stop repeating method request and reply messages

structure of 79structure

announcement message 53heartbeat reply message 75heartbeat request message 75method description reply message 58method description request message 57method descriptor message 60method invocation reply message 70method invocation request message 68parameter descriptor list message 64parameter descriptor message 66parameter list message when used to send

arguments 72parameter list message when used to send

results 72repeating method invocation request message 77,

77unsolicited message 87


Index | 155

structure of discovery request and reply messages 55structure of stop repeating method request and reply

messages 79support, contacting xix

T

table of data 95example of returning a 41

tablesreturning results in the form of 74

technical support xixthird AMI Phase

calling the methods 23TIBCO Hawk Requirements 2TIBCO Hawk security

AMI and 27TIBCO Hawk Security concepts 100TIBCO Hawk system

AMI is part of the 11TIBCO Rendezvous concepts used in AMI 13TIBCO Rendezvous messaging

AMI uses 4TIBCO_HOME xvii

U

unpack() 135unsolicited application messages 26unsolicited message 87

structure 87unsolicited message sending 49unsolicited messages

examining 98unsolicited messages window 98user-defined methods 25

method invocation of 47using a security policy 137using API with the AMI 31

V

validateId() 136

W

why use a management interface? 9window

AMI WorkBench main 92error messages 97unsolicited messages 98


tibco hawk programmer,aos guide · † tibco hawk administrator’s guide this manual includes...

Documents