Tib Hawk Ami Java Reference

8/17/2019 Tib Hawk Ami Java Reference

1/225

TIBCO Hawk ®

AMI Java Reference

Software Release 4.9November 2010


2/225

Important Information

SOME TIBCO SOFTWARE EMBEDS OR BUNDLES OTHER TIBCO SOFTWARE. USE OF SUCH EMBEDDEDOR BUNDLED TIBCO SOFTWARE IS SOLELY TO ENABLE THE FUNCTIONALITY (OR PROVIDE LIMITEDADD-ON FUNCTIONALITY) OF THE LICENSED TIBCO SOFTWARE. THE EMBEDDED OR BUNDLEDSOFTWARE IS NOT LICENSED TO BE USED OR ACCESSED BY ANY OTHER TIBCO SOFTWARE OR FORANY OTHER PURPOSE.

USE OF TIBCO SOFTWARE AND THIS DOCUMENT IS SUBJECT TO THE TERMS AND CONDITIONS OF ALICENSE AGREEMENT FOUND IN EITHER A SEPARATELY EXECUTED SOFTWARE LICENSEAGREEMENT, OR, IF THERE IS NO SUCH SEPARATE AGREEMENT, THE CLICKWRAP END USERLICENSE AGREEMENT WHICH IS DISPLAYED DURING DOWNLOAD OR INSTALLATION OF THESOFTWARE (AND WHICH IS DUPLICATED IN LICENSE FILE) OR IF THERE IS NO SUCH SOFTWARELICENSE AGREEMENT OR CLICKWRAP END USER LICENSE AGREEMENT, THE LICENSE(S) LOCATEDIN THE “LICENSE” FILE(S) OF THE SOFTWARE. USE OF THIS DOCUMENT IS SUBJECT TO THOSE TERMSAND CONDITIONS, AND YOUR USE HEREOF SHALL CONSTITUTE ACCEPTANCE OF AND ANAGREEMENT TO BE BOUND BY THE SAME.

This document contains confidential information that is subject to U.S. and international copyright laws andtreaties. No part of this document may be reproduced in any form without the written authorization of TIBCOSoftware Inc.

TIBCO, The Power of Now, TIBCO ActiveMatrix BusinessWorks, TIBCO Hawk, TIBCO Designer, TIBCORendezvous, TIBCO Enterprise Message Service, TIBCO Runtime Agent, TIBCO Administrator, TIBCOActiveEnterprise 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 SunMicrosystems, Inc. in the U.S. and other countries.

All other product and company names and marks mentioned in this document are the property of theirrespective owners and are mentioned for identification purposes only.

THIS SOFTWARE MAY BE AVAILABLE ON MULTIPLE OPERATING SYSTEMS. HOWEVER, NOT ALLOPERATING SYSTEM PLATFORMS FOR A SPECIFIC SOFTWARE VERSION ARE RELEASED AT THE SAMETIME. SEE THE README FILE FOR THE AVAILABILITY OF THIS SOFTWARE VERSION ON A SPECIFICOPERATING SYSTEM PLATFORM.

THIS DOCUMENT IS PROVIDED “AS IS” WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS ORIMPLIED, 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 BEINCORPORATED IN NEW EDITIONS OF THIS DOCUMENT. TIBCO SOFTWARE INC. MAY MAKEIMPROVEMENTS AND/OR CHANGES IN THE PRODUCT(S) AND/OR THE PROGRAM(S) DESCRIBED INTHIS DOCUMENT AT ANY TIME.

THE CONTENTS OF THIS DOCUMENT MAY BE MODIFIED AND/OR QUALIFIED, DIRECTLY ORINDIRECTLY, 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


3/225

TIBCO Hawk AMI Java Reference

| iii

Contents

Preface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ix

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

Related Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xi

TIBCO Hawk Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xi

Other TIBCO Product Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xiiThird-Party Documentation. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xii

Typographical Conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xiii

Connecting with TIBCO Resources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xv

How to Join TIBCOmmunity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xv

How to Access All TIBCO Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xv

How to Contact TIBCO Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xv

Chapter 1 Introduction. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1

The AMI Protocol . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2

The TIBCO Hawk AMI Java API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3

The AmiSession Class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3

The AmiMethod Class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3

The AmiAsyncMethod Class. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3

The AmiParameter and AmiParameterList Classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4

Error Logging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4

Use of Curly Brackets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4

AMI Java API Sample Programs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5

Chapter 2 Programmer’s Checklist . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .7

Programmer’s Checklist . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8

Chapter 3 Java Classes and Class Structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .9

Class Hierarchy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10

Interface Hierarchy. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11

Chapter 4 Java AmiSession Class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .13

AmiSession . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14

AmiSession() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17AmiSession.addMethod() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19


4/225


iv | Contents

AmiSession.addMethods(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20

AmiSession.announce(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21

AmiSession.getDisplayName() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22

AmiSession.getHelp() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23AmiSession.getMaxThreads() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24

AmiSession.getMethod() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25

AmiSession.getMethods() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26

AmiSession.getName() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27

AmiSession.getRvQueue() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28

AmiSession.getTrace(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29

AmiSession.sendData() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30

AmiSession.sendUnsolicitedMsg() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31AmiSession.setMaxThreads() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32

AmiSession.stop() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33

AmiSession.createCommonMethods() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34

Chapter 5 AMI Classes. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35

AmiAlertType . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36

AmiAlertType.toString() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37

AmiAlertType.fromString() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38

AmiAlertType.equals() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39

AmiAlertType.hashCode() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40

AmiConstants . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41

AmiErrors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42

AmiMethod . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43

AmiMethod.AmiMethod() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45

AmiMethod.equals(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47

AmiMethod.getArguments(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48

AmiMethod.getHelp(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49

AmiMethod.getIndexName() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50

AmiMethod.getName(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51

AmiMethod.getReturns() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52

AmiMethod.getSession() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53

AmiMethod.getTimeout() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54

AmiMethod.getType(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55

AmiMethod.onInvoke(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56

AmiMethod.setIndexName() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57

AmiMethod.setSession() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58

AmiAsyncMethod . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59

AmiAsyncMethod.AmiAsyncMethod() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60

AmiAsyncMethod.onStart() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62

AmiAsyncMethod.onStop() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63AmiAsyncMethod.onData() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64


5/225


Contents |v

AmiGetVersionMethod . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65

AmiGetVersionMethod.addComponentVersion() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66

AmiGetVersionMethod.getArguments() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67

AmiGetVersionMethod.getIndexName() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68AmiGetVersionMethod.getReturns(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69

AmiGetVersionMethod.onInvoke() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70

AmiMethodContext . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71

AmiMethodContext.getMethod(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72

AmiMethodContext.getDuration() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73

AmiMethodContext.getArguments() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74

AmiMethodContext.getReplySubject() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75

AmiMethodContext.getContext(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76AmiMethodContext.equals() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77

AmiMethodContext.hashCode() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78

AmiMethodType . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79

AmiMethodType.toString() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80

AmiMethodType.fromString() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81

AmiMethodType.equals() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82

AmiMethodType.hashCode() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83

ComponentVersion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84

ComponentVersion.ComponentVersion() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85

ComponentVersion.getComponentInfo() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86

Chapter 6 AMI Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .87

AmiParameter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88

AmiParameter.AmiParameter(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90

AmiParameter.getHelp() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92

AmiParameter.getLegalChoices(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93

AmiParameter.getName() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94

AmiParameter.getValue() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95

AmiParameter.getValueChoices(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 96

AmiParameter.setLegalChoices() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97

AmiParameter.setValueChoices(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98

AmiParameterList . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99AmiParameterList.AmiParameterList() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100

Chapter 7 AMI Interfaces. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .101

AmiEnabledInterface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102

AmiEnabledInterface.getMethods() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104

AmiEnabledInterface.setSession() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 105

AmiMethodInterface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 106AmiMethodInterface.getArguments() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 108


6/225


vi | Contents

AmiMethodInterface.getHelp() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109

AmiMethodInterface.getIndexName() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 110

AmiMethodInterface.getName(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111

AmiMethodInterface.getReturns() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112AmiMethodInterface.getSession() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113

AmiMethodInterface.getTimeout() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114

AmiMethodInterface.getType() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115

AmiMethodInterface.onInvoke() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 116

AmiMethodInterface.setIndexName() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117

AmiMethodInterface.setSession() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 118

AmiAsyncMethodInterface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 119

AmiAsyncMethodInterface.onStart() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 120AmiAsyncMethodInterface.onStop() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121

AmiTraceInterface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122

AmiTraceInterface.getDirectoryName() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 126

AmiTraceInterface.getFileName() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 127

AmiTraceInterface.getFileSize() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 128

AmiTraceInterface.getLevel() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 129

AmiTraceInterface.getLevelHelpString() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 130

AmiTraceInterface.getLevelLabelString() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131

AmiTraceInterface.getLevelString() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132

AmiTraceInterface.getMaxFile() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 133

AmiTraceInterface.getMaxLevel(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 134

AmiTraceInterface.getNumberOfLevels() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 135

AmiTraceInterface.isLevelOn() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 136

AmiTraceInterface.log() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 137

AmiTraceInterface.logAlways(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 138

AmiTraceInterface.logAmi() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 139

AmiTraceInterface.logDebug() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 140

AmiTraceInterface.logError() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 141

AmiTraceInterface.logInfo() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 142

AmiTraceInterface.logWarning(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 143

AmiTraceInterface.setDirectoryName() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 144

AmiTraceInterface.setFileName(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 145

AmiTraceInterface.setFileSize() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 146AmiTraceInterface.setLevel() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 147

AmiTraceInterface.setMaxFile() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 148

AmiTraceInterface.setUserLevel() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 149

Chapter 8 AMI Exception Classes. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 151

HawkException . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 152

HawkException.HawkException() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 154

HawkException.getCode() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 155

HawkException.getMax(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 156


7/225


Contents |vii

HawkException.getMessage() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 157

HawkException.getMin(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 158

AmiException . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 159

AmiException.AmiException() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 160

ResourceException . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 161

ResourceException.ResourceException() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 162

TraceException . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 163

TraceException.TraceException() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 164

Chapter 9 Error and Debug Classes. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .165

Trace . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 166Trace.Trace(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 172

Trace.getDirectoryName(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 174

Trace.getFileName() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 175

Trace.getFileSize() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 176

Trace.getLevel() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 177

Trace.getLevelHelpString() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 178

Trace.getLevelLabelString() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 179

Trace.getLevelString(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 180

Trace.getMaxFile() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 181

Trace.getMaxLevel() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 182

Trace.getNumberOfLevels() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 183

Trace.getOutputStream() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 184

Trace.isLevelOn() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 185

Trace.log(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 186

Trace.setDateTimeFormat() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 187

Trace.setDirectoryName(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 188

Trace.setFileName() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 189

Trace.setFileSize() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 190

Trace.setLevel() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 191

Trace.setMaxFile() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 192

Trace.setUserLevel(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 193

AmiTrace . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 194

AmiTrace() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 196AmiTrace.getMethods(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 197

AmiTrace.logAlways() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 198

AmiTrace.logAmi() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 199

AmiTrace.logDebug() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 200

AmiTrace.logError(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 201

AmiTrace.logInfo(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 202

AmiTrace.logWarning() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 203

AmiTrace.setSession() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 204TraceErrors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 205


8/225


viii | Contents

HawkErrors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 206

Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 207


9/225


| ix

Preface

This manual describes the TIBCO Hawk® Application Programming Interface(API) for Java programmers. The first part of this manual deals with the conceptsinvolved in writing API programs for the TIBCO Hawk monitoring system. Thefollowing sections deal with the specific API programming components.

This manual assumes you are familiar with TIBCO Rendezvous architecture andthe concepts of system monitoring.

Topics

• Changes from the Previous Release of this Guide, page x• Related Documentation, page xi

• Typographical Conventions, page xiii

• Connecting with TIBCO Resources, page xv


10/225


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


11/225


Preface |xi

Related Documentation

This section lists documentation resources you may find useful.

TIBCO Hawk Documentation

The following documents form the TIBCO Hawk documentation set:

• TIBCO Hawk Installation and Configuration Read this book first. It containsstep-by-step instructions for installing TIBCO Hawk software on various

operating system platforms. It also describes how to configure the softwarefor specific applications, once it is installed. An installation FAQ is included.

• TIBCO Hawk Administrator’s Guide This manual includes basic descriptions ofTIBCO 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 developmenttool, and the TIBCO Hawk security framework and its classes. Programmersshould then refer to the appropriate language reference for the AMI API. TheTIBCO Hawk Application Management Interface (AMI) exposes internalapplication methods to TIBCO Hawk.

• TIBCO Hawk AMI C Reference Contains detailed descriptions of each datatypeand function in the TIBCO Hawk C AMI API.

• TIBCO Hawk AMI C++ Reference Contains detailed descriptions of eachdatatype and function in the TIBCO Hawk C++ AMI API.

• TIBCO Hawk AMI Java Reference Contains detailed descriptions of each classand method in the TIBCO Hawk Java AMI API.

• TIBCO Hawk Console API Reference Contains detailed descriptions of eachclass and method in the TIBCO Hawk Console API, a set of Java interfacesthat allow you to manage and interact with TIBCO Hawk agents and monitoralerts generated by these agents.

• TIBCO Hawk Configuration Object API Reference Contains detailed descriptionsof 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.


12/225


xii | Related Documentation

• TIBCO Hawk HTTP Adapter User’s Guide Contains information aboutperforming 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 toadminister and monitor the TIBCO Enterprise Message Service server.

• TIBCO Hawk Release Notes Read the release notes for a list of new and changedfeatures. This document also contains lists of known issues and closed issuesfor this release.

Other TIBCO Product Documentation

You may find it useful to read the documentation for the following TIBCOproducts:

• TIBCO Rendezvous®

— TIBCO Rendezvous Concepts

— TIBCO Rendezvous Administration

— TIBCO Rendezvous Configuration Tools

• TIBCO Enterprise Message Service™

— TIBCO Enterprise Message Service Installation

— TIBCO Enterprise Message Service User’s Guide

• TIBCO Administator™

— TIBCO Administrator Installation Guide

Third-Party Documentation

You may find the following third-party documentation useful.

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


13/225


Preface |xiii

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. Thisdirectory is referenced in documentation as TIBCO_HOME. The value ofTIBCO_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 beinstalled into different installation environments.

A TIBCO configuration folder stores configuration data generated by TIBCOproducts. Configuration data can include sample scripts, session data,configured binaries, logs, and so on. This folder is referenced in documentationas CONFIG_FOLDER.

TIBCO Hawk installs into a directory within . This directory isreferenced in documentation as HAWK_HOME. The value of HAWK_HOME depends on the operating system. For example on Windows systems, the defaultvalue is C:\tibco\hawk\4.9.

code font Code font identifies commands, code examples, filenames, pathnames, andoutput 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 ofparticular interest.

• In command syntax, to indicate the default parameter for a command. Forexample, if no parameter is specified, MyCommand is enabled:MyCommand [enable | disable]


14/225


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

Keycombinations

Key name separated by a plus sign indicate keys pressed simultaneously. Forexample: Ctrl+C.

Key names separated by a comma and space indicate keys pressed one after theother. 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 applythe 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

P f |


15/225


Preface |xv

Connecting with TIBCO Resources

How to Join TIBCOmmunity

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

How to Access All TIBCO Documentation

After you join TIBCOmmunity, you can access the documentation for allsupported product versions here:

http://docs.tibco.com/TibcoDoc

How to Contact TIBCO SupportFor comments or problems with this manual or the software it addresses, pleasecontact TIBCO Support as follows.

• For an overview of TIBCO Support, and information about getting startedwith 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 username, you can request one.

xvi | Connecting with TIBCO Resources

http://www.tibcommunity.com/http://docs.tibco.com/TibcoDochttp://www.tibco.com/services/supporthttps://support.tibco.com/https://support.tibco.com/http://www.tibco.com/services/supporthttp://docs.tibco.com/TibcoDochttp://www.tibcommunity.com/


16/225


xvi | Connecting with TIBCO Resources

|1


17/225


|1

Chapter 1 Introduction

This chapter describes the TIBCO Hawk API for Java programmers.

Each Java class, interface, constructor, and method will be found in theappropriate section. Class and interface descriptions, summary tables, anddetailed member descriptions are given. Methods within the classes andinterfaces have their own pages.

Topics

• The AMI Protocol, page 2

• The TIBCO Hawk AMI Java API, page 3

• AMI Java API Sample Programs, page 5

2 | Chapter 1 Introduction


18/225



The AMI Protocol

The TIBCO Hawk Application Management Interface (AMI) protocol is aspecification of TIBCO Rendezvous messages that define the interactions betweenan AMI manager and an AMI application. An AMI manager is any applicationthat monitors or manages AMI applications, or both, via the AMI protocol. ATIBCO Hawk agent is an example of an AMI manager. An AMI applicationexposes internal methods that allow AMI managers to manage and monitor thatapplication by exchanging data and events with it.

You should first read and understand the discussion of the AMI protocol in theTIBCO Hawk Programmer’s Guide before attempting to use the AMI Java APIdescribed in this manual.

The TIBCO Hawk AMI Java API |3


19/225


|

The TIBCO Hawk AMI Java API

The AMI Java API facilitates the development of AMI applications written in the Java programming language. This API makes AMI application developmenteasier and more foolproof because it takes care of all the AMI and TIBCORendezvous protocol details for you. The API also ensures that your applicationwill be compatible with future releases of TIBCO Hawk and AMI.

The AmiSession Class

An AMI application written with the AMI Java API centers on the AmiSession class. The AmiSession class encapsulates the AMI application’s entire interactionwith an AMI manager. The AmiSession class provides an AMI session withmethods to create the session, announce it, and to exchange data, events, anderrors with the AMI session.

The AmiMethod ClassAn AMI application consists of a set of AMI methods that can be invoked by anAMI manager. The AmiMethod class encapsulates the definition and processing ofthese AMI methods.

The method class provides methods to create, and process invocations of yourAMI methods. AmiMethod objects are created and added to your AMI sessionobjects. The AMI session announces method objects (sends their descriptions to

an AMI manager) and detects invocations of your AMI methods. The AMI sessionobject invokes your methods by means of the onInvoke() method of the AMImethod class.

The AmiAsyncMethod Class

The AmiAsyncMethod class implements asynchronous AMI methods, so that datacan be returned to an AMI manager as soon as it becomes available. In a typicalscenario, when the manager requires data, it polls the method by means of asynchronous data call. The AmiAsyncMethod class allows data to be returnedasynchronously, as well.

If the source of your method's data is truly event-driven, the AmiAsyncMethod class allows your application to send the data as events occur. This eliminatespolling and allows the manager to also be event-driven, with respect to thismethod's data. The manager must inform the AMI application of when it has an

interest in receiving data from one of your asynchronous methods and alsoinform it when it no longer has an interest in the data.



20/225


|

The manager can have several subscriptions. Each subscription is represented bya unique context. The application receives this unique context along with theinput parameters for each subscription. The tracking of each context and its

associated input parameters is done by the AmiSession. The application is nolonger responsible for the tracking of contexts.

The AmiParameter and AmiParameterList Classes

During an invocation, an AmiMethod object receives input parameters and returnsoutput parameters. The AmiParameter class encapsulates a single input or outputparameter. The AmiParameter class provides methods to create and set/get the

parameter's value.

A method can also return multiple rows of data (tabular data) by specifyingmultiple instances of its output parameters during a method invocation. Amethod that returns tabular data must define one or more indexes to uniquelyindex each row. An index is specified by the name(s) of the output parameterswhose values form the index.

The AmiParameterList class is used to group AmiParameter objects to define acomplete set of input and/or output parameters for an AmiMethod.

Error Logging

The AMI Java API provides rolling trace files to log error or debug messages foryour AMI session. The AmiTrace class provides methods to configure and logmessages to your trace log. The AMI Java API has built-in tracing, which can be

turned on and off, based on trace category (for example, INFO, WARNING, DEBUG).

Use of Curly Brackets

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

AMI Java API Sample Programs |5


21/225


|

AMI Java API Sample Programs

The TIBCO Hawk software distribution includes sample AMI Java API programsthat will help you to better understand how to use the API. These samples can befound in the directory /samples/ami_api/java. Refer to the TIBCO Hawk Installation and Configuration forinstructions on building and executing these sample applications.



22/225


|7


23/225


Chapter 2 Programmer’s Checklist

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

Topics

• Programmer’s Checklist, page 8


24/225

|9


25/225


Chapter 3 Java Classes and Class Structure

This chapter provides a diagram showing organization of the TIBCO Hawk AMIAPI Java classes.

Topics

• Class Hierarchy, page 10

• Interface Hierarchy, page 11

10 | Chapter 3 Java Classes and Class Structure


26/225


Class Hierarchy

The general hierarchy for Java class objects is as follows:

Classes under java.lang.object:

java.util.AbstractCollectionjava.util.AbstractList

java.util.VectorCOM.TIBCO.hawk.ami., AmiParameterList

COM.TIBCO.hawk.ami.AmiParameterListCOM.TIBCO.hawk.ami.AmiAlertTypeCOM.TIBCO.hawk.ami.AmiConstantsCOM.TIBCO.hawk.ami.AmiErrorsCOM.TIBCO.hawk.ami.AmiMethod

COM.TIBCO.hawk.ami.AmiAsyncMethodCOM.TIBCO.hawk.ami.AmiGetVersionMethod

COM.TIBCO.hawk.ami.AmiMethodContextCOM.TIBCO.hawk.ami.AmiMethodTypeCOM.TIBCO.hawk.ami. AmiParameterCOM.TIBCO.hawk.ami.AmiSession

COM.TIBCO.hawk.ami.ComponentVersionCOM.TIBCO.hawk.utilities.exception.HawkErrorsCCOM.TIBCO.hawk.utilities.exception.HawkErrorsjava.lang.Throwablejava.lang.Exception

COM.TIBCO.hawk.utilities.exception.HawkExceptionCOM.TIBCO.hawk.ami.AmiExceptionCOM.TIBCO.hawk.utilities.trace.TraceException

COM.TIBCO.hawk.utilities.trace.TraceCOM.TIBCO.hawk.ami.AmiTrace

COM.TIBCO.hawk.ami.AmiTraceInterfaceCOM.TIBCO.hawk.utilities.trace.TraceErrors

Interface Hierarchy |11


27/225


Interface Hierarchy

The following diagram shows the interface hierarchy under java.lang.object.

COM.TIBCO.hawk.utilities.trace.Trace

COM.TIBCO.hawk.ami.AmiTraceCOM.TIBCO.hawk.ami.AmiTraceInterface

COM.TIBCO.hawk.ami.AmiEnabledInterfaceCOM.TIBCO.hawk.ami.AmiMethodInterfaceCOM.TIBCO.hawk.ami.AmiAsyncMethodInterface

COM.TIBCO.hawk.ami.AmiParameterList

12 | Chapter 3 Java Classes and Class Structure


28/225


|13


29/225


Chapter 4 Java AmiSession Class

This chapter outlines the TIBCO Hawk AMI API Java Session class. TheAmiSession class handles the interface between the Java applicationprogramming interface and the Application Management Interface (AMI)protocol.

Table 8 shows the classes used in Java programming for the TIBCO Hawk

software.

Topics

• AmiSession, page 14

14 | Chapter 4 Java AmiSession Class


30/225


AmiSession

Class

Class under java.lang.Object:COM.TIBCO.hawk.ami.AmiSession

Declaration public class AmiSessionextends java.lang.Objectimplements AmiEnabledInterface

Purpose The AmiSession class and its supporting class objects provide a Java applicationprogramming interface (API), which implements the AMI protocol in Javalanguage.

Remarks Applications instrumented with TIBCO Hawk AMI define a set of synchronousmethods (AmiMethodInterface), and/or asynchronous methods(AmiAsyncMethodInterface), through which the application is monitored andmanaged by TIBCO Hawk software. Applications instrumented with TIBCOHawk software function as a TIBCO Hawk Microagent.

An AmiSession object must be identified by a unique name, with an optionalhelp text to describe the functionality of the application.

Fields public static final int DEFAULT_MAX_THREADSpublic static final int MAX_MAX_THREADS

Field Summary Field Meaning

DEFAULT_MAX_THREADS The default maximum number of invocationprocessing threads this AmiSession is to create.This default maximum is currently set to 1.

MAX_MAX_THREADS The maximum number of invocation processingthreads this AmiSession is allowed to create.This maximum number is currently set to 9.

AmiSession |15


31/225


Member

SummaryMember Description Page

AmiSession() Constructor. 17

Methods to Add Interface Objects

AmiSession.addMethod() Adds the specifiedAmiMethodInterface object tothis AmiSession.

19

AmiSession.addMethods() Adds the array of methods defined by the specifiedAmiEnabledInterface object to

this session.

20

Discovery Method

AmiSession.announce() Send the discovery message to theTIBCO Hawk agent.

21

Stop Method

AmiSession.stop() Stops the AMI session. 33

Accessor Methods

AmiSession.getHelp() Returns the help text for this AMIsession.

23

AmiSession.getMaxThreads() Returns the maximum number ofinvocation processing threads thisAmiSession is allowed to create.

24

AmiSession.getMethod() Retrieve theAmiMethodInterface object byits name.

25

AmiSession.getMethods() Returns an array ofAmiMethodInterfaces for

getting and setting AMI session'snumber of threads.

26

AmiSession.getName() Returns the name of this AMIsession.

27

AmiSession.getRvQueue() Returns the RvQueue used to createthis AmiSession.

28



32/225


See Also AmiSession.getMaxThreads(), page 24AmiSession.sendData(), page 30

AmiSession.getTrace() Returns the AmiTraceInterface object used to create this

AmiSession.

28

Methods to Send Data

AmiSession.sendData() Sends data to subscriber accordingto the specified methodsubscription context.

30

AmiSession.sendUnsolicitedMsg() The method sends unsolicited

message to TIBCO Hawk agent to be processed by rulebases via theonUnsolicitedMsg() method

31

Methods to Set Parameters

AmiSession.setMaxThreads() Sets the maximum number ofinvocation processing thread thisAmiSession is allowed to create.

32

AmiSession.createCommonMethods() Creates the following methods forthe AmiSession:

getReleaseVersion

getTraceLevel

setTraceLevel

getTraceParameters

setTraceParameters

34

Member (Cont’d) Description (Cont’d) Page

AmiSession() |17


33/225


AmiSession()

Constructor

Declaration public AmiSession(com.tibco.tibrv.TibrvTransport rvTransport,com.tibco.tibrv.TibrvQueue rvQueue,java.lang.String amiSessionName,java.lang.String amiSessionDisplay,java.lang.String amiSessionHelp)

throws AmiException

public AmiSession(com.tibco.tibrv.TibrvTransport rvTransport,

com.tibco.tibrv.TibrvQueue rvQueue,java.lang.String amiSessionName,java.lang.String amiSessionDisplay,java.lang.String amiSessionHelp,AmiTraceInterface trace)

throws AmiException

public AmiSession(java.lang.String service,java.lang.String network,

java.lang.String daemon,com.tibco.tibrv.TibrvQueue rvQueue,java.lang.String amiSessionName,java.lang.String amiSessionDisplay,java.lang.String amiSessionHelp)

throws AmiException

public AmiSession(java.lang.String service,java.lang.String network,

java.lang.String daemon,com.tibco.tibrv.TibrvQueue rvQueue,java.lang.String amiSessionName,java.lang.String amiSessionDisplay,java.lang.String amiSessionHelp,AmiTraceInterface trace)

throws AmiException

Purpose Creates an instance of class AmiSession. Each instance of this class corresponds to

an independent TIBCO Hawk Microagent.

Remarks The first constructor generates a default AmiTrace object to implement theAmiTraceInterface interface.

Parameters Parameter Description

rvTransport The TibrvTransport object.

rvQueue The TibrvQueue object.



34/225


See Also AmiTraceInterface, page 122AmiTrace, page 194

amiSessionName Name to uniquely identify this amiSession as aTIBCO Hawk microagent. Cannot be null or an

empty string.

amiSessionDisplay User-friendly name string for microagent.

amiSessionHelp Help text for describing the functionality of thisTIBCO Hawk microagent.

service Specifies which User Datagram Protocol (UDP)service group the TIBCO Rendezvous daemon

should use for session communications. Thedefault configuration uses the service portnumber 7474. A service can be specified either byits name or its port number.

network Specifies what network to use for outboundsession communications when a computer isconnected to more than one network. A networkcan be specified by its name or by its IP address.

This parameter is also used to specify themulticast groups to use for communication.

daemon Specifies which TIBCO Rendezvous daemon is tohandle communication for the session. A localdaemon is specified by the communications type(always tcp) and a socket number (e.g., 7474). Thedefault configuration uses the local daemon with

the TCP socket number 7474.trace An instance of the AmiTraceInterface

implementation.

Parameter Description

AmiSession.addMethod() |19

A iS i ddM th d()


35/225


AmiSession.addMethod()

Method

Declaration public void addMethod(AmiMethodInterface method)throws AmiException

Purpose Adds the specified AmiMethodInterface object to this AmiSession.

Remarks The following method validation checks are performed on the specified AMImethod. AmiException is thrown if the AMI method does not comply with thefollowing rules:

• Method name must be a non-null and non-empty string.

• Method name must not start with the '_' (underscore) character.

• Method name must be unique for each AmiSession.

• Method type must be one of the following:

— AmiConstants.METHOD_TYPE_INFO

— AmiConstants.METHOD_TYPE_ACTION — AmiConstants.METHOD_TYPE_ACTION_INFO

• All method parameter names must be non-null and non-empty strings.

• All method parameter names must be unique for each method and for eachinput/output parameter list.

• All method parameter must be specified with a sample value.

• If the method type is AmiConstants.METHOD_TYPE_INFO orAmiConstants.METHOD_TYPE_ACTION_INFO, then its getReturns() methodmust return a non-null and non-empty AmiParameterList object.

• If the method returns multiple rows of data, it must specify an indexparameter name. The index parameter name must exist in its returnAmiParameterList.

Parameters

Throws An AmiException is thrown because of one of the following conditions:

• The specified method has already been added to an AMI session.

• The application has already announced this AMI session.


method The method to be added to this AmiSession.


AmiSession addMethods()


36/225


AmiSession.addMethods()

Method

Declaration public void addMethods(AmiEnabledInterface amiEnabled)throws AmiException

Purpose Adds the array of methods defined by the specified AmiEnabledInterface objectto this session.

Remarks This method first invokes the AmiEnabledInterface.setSession() method ofthe specified AMI-enabled object, using the current AMI session. Then, the array

of AmiMethodInterface is obtained through itsAmiEnabledInterface.getMethods() method. This method then adds eachAmiMethodInterface object to this AMI session.

AmiMethodInterface validation rules for this method are the same as those forAmiSession.addMethod(AmiMethodInterface) .

Parameters

Throws AmiException is thrown if one the following conditions is true:

• The specified amiEnabled object is null.

• The AMI session has already announced itself.

See Also AmiEnabledInterface, page 102

AmiSession.addMethod(), page 19


amiEnabled An object that implements the AmiEnabledInterface interface.

AmiSession.announce() |21

AmiSession announce()


37/225


AmiSession.announce()

Method

Declaration public void announce()throws AmiException

Purpose This method sends the discovery message to the TIBCO Hawk agent.

Remarks Once the AMI session announces itself, the application should not attempt to addnew AMI methods to the session. Attempts to do so raise an exception.

Throws AmiException is thrown if this method fails to send the discovery message.


AmiSession getDisplayName()


38/225


AmiSession.getDisplayName()

Method

Declaration public java.lang.String getDisplayName()

Purpose Returns the display name of this AMI session.

Returns String representing the name of the session for display.

AmiSession.getHelp() |23

AmiSession getHelp()


39/225


AmiSession.getHelp()

Method

Declaration public java.lang.String getHelp()

Purpose This method returns the help text message of this AMI session.

Returns String representing the help text.


AmiSession.getMaxThreads()


40/225


AmiSession.getMaxThreads()

Method

Declaration public int getMaxThreads()

Purpose Returns the maximum number of invocation processing thread this AMI sessionis allowed to create.

Returns The maximum number of invocation processing threads.

AmiSession.getMethod() |25

AmiSession.getMethod()


41/225


g ()

Method

Declaration public AmiMethodInterface getMethod(java.lang.String methodName)throws AmiException

Purpose Retrieve the AmiMethodInterface object by its name.

Parameters

Returns AmiMethodInterface corresponding to the specified name. If no method object isknown by this name, then null is returned.

Throws AmiException is thrown if methodName is null.


methodName Name of the method to retrieve.


AmiSession.getMethods()


42/225


g ()

Method

Declaration public AmiMethodInterface[] getMethods()throws AmiException

Purpose Returns an array of AmiMethodInterface objects for getting and setting the AMIsession’s number of threads.

Remarks This method implements the AmiEnabledInterface such that an array of twoAmiMethodInterfaces for getting and setting the number of AMI invocationprocessing threads are returned.

The AmiMethodInterfaces returned by this method are:

• getMaxThreads

• setMaxThreads

Specified By getMethods in interface AmiEnabledInterface

Returns Parameter Description

AmiMethodInterface[] The interface: either getMaxThreads orsetMaxThreads.

AmiSession.getName() |27

AmiSession.getName()


43/225


Method

Declaration public java.lang.String getName()

Purpose Returns the name of this AMI session.

Returns String representing the AMI session name.


AmiSession.getRvQueue()


44/225


Method

Declaration public com.tibco.tibrv.TibrvQueue getRvQueue()

Purpose Returns the TibrvQueue object used to create this AMI session.

Returns TibrvQueue

AmiSession.getTrace() |29

AmiSession.getTrace()


45/225


Method

Declaration public AmiTraceInterface getTrace()

Purpose Returns the AmiTraceInterface object used to create this AmiSession.

Returns AmiTraceInterface

See Also AmiTraceInterface, page 122


AmiSession.sendData()


46/225


Method

Declaration public final void sendData(AmiMethodContext context,AmiParameterList data)

throws AmiException

Purpose Sends data to the subscriber, according to the specified method subscriptioncontext.

Remarks When data from an AMI asynchronous method becomes available, this method

allows the application to publish the data. This method is called byAmiAsyncMethod.onData().

Parameters

Throws AmiException is thrown if incorrect data is passed or if the publication fails.

See Also AmiMethodContext, page 71


context The context associated with a particular subscription to whichdata is to be sent.

data The data to be published.

AmiSession.sendUnsolicitedMsg() |31

AmiSession.sendUnsolicitedMsg()


47/225


Method

Declaration public void sendUnsolicitedMsg(AmiAlertType type,java.lang.String text,java.lang.Integer id)

throws AmiException

Purpose The method sends an unsolicited message to the TIBCO Hawk agent, to beprocessed by rulebases using the onUnsolicitedMsg() method.

Parameters

Throws AmiException is thrown if incorrect data has been passed or if the AMI objectwas unable to send a message to the TIBCO Hawk agent.

See Also AmiConstants, page 41


type Type of the unsolicited message.

text User-defined text message.

id Message id.


AmiSession.setMaxThreads()

M th d


48/225


Method

Declaration public void setMaxThreads(int max)throws AmiException

Purpose Sets the maximum number of invocation processing threads this AmiSession isallowed to create.

Parameters

Throws AmiException is thrown if the specified maximum value is less than one (1) orgreater than MAX_MAX_THREADS

See Also AmiSession(), page 17


max Maximum number of invocation processing threads.

AmiSession.stop() |33

AmiSession.stop()

Method


49/225


Method

Declaration public void stop()throws AmiException

Purpose Stops the AMI session. All associated Hawk agents are notified that this AMIsession is no longer running or supported. These agents will remove theassociated microagent from their microagent lists. This AMI session will beinactive until AmiSession.announce() is called to re-activate this session.

Throws AmiException is thrown if this method fails to stop the AMI session.


50/225

|35

Chapter 5 AMI Classes


51/225


This chapter is a reference to the TIBCO Hawk Application Management Interface(AMI) Java classes.

Topics

• AmiAlertType, page 36

• AmiConstants, page 41

• AmiErrors, page 42

• AmiMethod, page 43

• AmiAsyncMethod, page 59

• AmiGetVersionMethod, page 65

• AmiMethodContext, page 71

• AmiMethodType, page 79

• ComponentVersion, page 84

36 | Chapter 5 AMI Classes

AmiAlertType

Class


52/225


COM.TIBCO.hawk.ami.AmiAlertType

Declaration public class AmiAlertType extends java.lang.Object;

Purpose The AmiAlertType class indicates the kind of unsolicited AMI message to send.This class does not provide a public constructor. Instead, three static objects of thisclass are available in the AmiConstants class. These are:

AmiConstants.ALERT_TYPE_INFO

AmiConstants.ALERT_TYPE_WARNING

AmiConstants.ALERT_TYPE_ERROR

Method

SummaryMethod Description Page

AmiAlertType.toString() Returns the string representation of theAMI alert type object.

37

AmiAlertType.fromString() Returns the type object according to the

input type string.

38

AmiAlertType.equals() Determines whether the specified alerttype is equivalent with this object.

39

AmiAlertType.hashCode() Returns a hash code value for theobject.

40

AmiAlertType.toString() |37

AmiAlertType.toString()

Method


53/225


Declaration public java.lang.String toString()

Purpose Returns the string representation of the AMI alert type object.

Returns The string representation of this object. Possible return strings are:

• INFO - Information alert.

• WARNING - Warning alert

• ERROR - Error alert. information.

Overrides toString in class java.lang.Object

See Also AmiConstants, page 41

AmiErrors, page 42


AmiAlertType.fromString()

Method


54/225


Declaration public static AmiAlertType fromString(java.lang.String typeString)

Purpose Returns the type object, corresponding to the input type string.

Remarks If null is specified as the typeString, then the AmiConstants.ALERT_TYPE_INFO object is returned.

Parameters Parameter Description

typeString String form of the AMI method type.

AmiAlertType.equals() |39

AmiAlertType.equals()

Method


55/225


Declaration public boolean equals(AmiAlertType type)

Purpose Determines whether the specified method type is equivalent with this object.

Parameters

Returns True if the two objects are equivalent. False otherwise.


type AMI method type.


AmiAlertType.hashCode()

Method


56/225


Declaration public int hashCode()

Purpose Returns a hash code value for the object.

Remarks This method is supported for the support of hash tables, such as those provided by java.util.Hashtable.

Returns The object’s hash code.

Overrides hashCode in class java.lang.Object

AmiConstants |41

AmiConstants

Class


57/225


COM.TIBCO.hawk.ami.AmiConstants

Declaration public class AmiConstants extends java.lang.Object

Purpose This is a static class that defines global constants.

Constructor public AmiConstants()

Fields public static final java.lang.String VERSION

public static final AmiMethodType METHOD_TYPE_INFOpublic static final AmiMethodType METHOD_TYPE_ACTIONpublic static final AmiMethodType METHOD_TYPE_ACTION_INFOpublic static final AmiAlertType ALERT_TYPE_INFOpublic static final AmiAlertType ALERT_TYPE_WARNINGpublic static final AmiAlertType ALERT_TYPE_ERROR

Field Summary Member Description

VERSION TIBCO Hawk AMI version. This API currentlyimplements the TIBCO Hawk AMI Protocol 1.2specification

METHOD_TYPE_INFO AMI method that returns information only.

METHOD_TYPE_ACTION AMI method that performs user-defined actions.

METHOD_TYPE_ACTION_INFO AMI method that both performs user-definedactions and returns information.

ALERT_TYPE_INFO AMI method that returns information.

ALERT_TYPE_WARNING AMI method that returns an alert.

ALERT_TYPE_ERROR AMI method that returns an error condition.


AmiErrors

Class


58/225


COM.TIBCO.hawk.ami.AmiErrors

Declaration public class AmiErrors extends java.lang.Object;

Purpose The AmiErrors class contains a set of static error code definitions for theCOM.TIBCO.hawk.ami package. The instance object of this class does not exist

because it does not support a constructor.

Remarks This class does not provide a public constructor.

Field

Declarations

public static final int AMI_INVALID_OPERATION_ERRpublic static final int AMI_METHOD_FORMAT_ERRpublic static final int AMI_REPLY_ERRpublic static final int AMI_RV_ERR

Fields Field Description

AMI_INVALID_OPERATION_ERROR Error code to indicate that an invalid operation

was performed.

AMI_METHOD_FORMAT_ERROR Error code to indicate that a method formaterror occurred.

AMI_REPLY_ERROR Error code to indicate that a reply erroroccurred.

AMI_RV_ERROR Error code to indicate that a TIBCO

Rendezvous error occurred.

AmiMethod |43

AmiMethod

Class

COM TIBCO h k i A iM th d


59/225


COM.TIBCO.hawk.ami.AmiMethod

AmiAsyncMethod

AmiGetVersionMethod

Declaration public abstract class AmiMethodextends java.lang.Objectimplements AmiMethodInterface

Purpose Implements the AmiMethodInterface as an abstract class.

Remarks Classes that extend from this AmiMethod abstract class must implement thefollowing methods:

• AmiMethod.getArguments()

• AmiMethod.getReturns()

• AmiMethod.onInvoke()

Member

SummaryMethod Description Page

AmiMethod.AmiMethod() Constructor 45

AmiMethod.equals() Compares if the specified AMI method isequivalent of this AMI method.

47

AmiMethod.getArguments() Returns an AmiParameterList that

describes the input arguments of thisAMI method.

48

AmiMethod.getHelp() Return the help text of the method. 49

AmiMethod.getIndexName() Returns the name of the outputparameter that serves as the index name.

50

AmiMethod.getName() Return the name of this method. 51

AmiMethod.getReturns() Returns an AmiParameterList thatserves to describe the output returnarguments of this AMI method.

52

AmiMethod.getSession() Returns the AmiSession object that thismethod belongs to.

53


AmiMethod.getTimeout() Returns the timeout interval of this AMImethod.

54

Method Description Page


60/225


AmiMethod.getType() Return the type object of this AMImethod.

55

AmiMethod.onInvoke() This method is invoked by the AMI JavaAPI when a method invocation arrivesfrom the managing TIBCO Hawk agent.

57

AmiMethod.setIndexName() Sets the AMI method's index parametername.

57

AmiMethod.setSession() Sets the AmiSession for this method. 58

AmiMethod.AmiMethod() |45

AmiMethod.AmiMethod()

Constructor


61/225


Declaration public AmiMethod(java.lang.String name,java.lang.String help,AmiMethodType type)

public AmiMethod(java.lang.String name,java.lang.String help,AmiMethodType type,java.lang.String indexName)

public AmiMethod(java.lang.String name,java.lang.String help,AmiMethodType type,java.lang.String [] indexName)

public AmiMethod(java.lang.String name,java.lang.String help,AmiMethodType type,int timeout)

public AmiMethod(java.lang.String name,java.lang.String help,AmiMethodType type,int timeout,java.lang.String indexName)

public AmiMethod(java.lang.String name,java.lang.String help,AmiMethodType type,int timeoutjava.lang.String [] indexName)

Purpose Constructor for creating an instance of AmiMethod object.

• The first form creates an AmiMethod with no index (method does not returnmultiple rows of data).

• The second form allows the user to create an AmiMethod with a specific indexfor the purpose of returning multiple rows of data in one single constructor, asopposed to creating the method, then using the setIndexName() method to setthe index.


• The second form allows the user to create an AmiMethod with a compositeindex for the purpose of returning multiple rows of data in one singleconstructor.


62/225


Remarks This constructor does not perform input argument validation. Validation isperformed only with AmiSession.addMethod.

Parameters

See Also AmiSession, page 14

AmiTraceInterface.getLevelString(), page 132

AmiErrors, page 42,

AmiConstants, page 41


name Name of method.

help Help text of method.

type Type of method. The type parameter must be one of thefollowing:

AmiConstants.METHOD_TYPE_INFO

AmiConstants.METHOD_TYPE_ACTION

AmiConstants.METHOD_TYPE_ACTION_INFO

timeout Timeout period used by the method.

The agent will timeout and stop listening to the microagentif it does not receive any response from the microagentwithin the time specified in the timeout field.

indexName AMI method parameter that serves as the index.

AmiMethod.equals() |47

AmiMethod.equals()

Method

D l ti bli b l l (A iM th dI t f th d)


63/225


Declaration public boolean equals(AmiMethodInterface method)

Purpose Compares the specified AMI method with this AMI method.

Remarks Two AMI methods are said to be equivalent if they have the same AMI methodnames.

Parameters

Returns True if the specified method is equivalent to this method, otherwise false.


method Method to compare.


AmiMethod.getArguments()

Method

Declaration public abstract AmiParameterList getArguments()


64/225


Declaration public abstract AmiParameterList getArguments()

Purpose Returns an AmiParameterList that describes the input arguments of this AMImethod.

Remarks Subclasses of the AmiMethod class must implement this method for the purpose ofreturning the method input arguments specification. If the AMI method does nothave any input arguments, then null is returned.

Specified by getArguments in interface AmiMethodInterface

Returns Input arguments of this AMI method.

AmiMethod.getHelp() |49

AmiMethod.getHelp()

Method

Declaration public final java lang String getHelp()


65/225


Declaration public final java.lang.String getHelp()

Purpose Returns the help text of the method.

Remarks The constructor of this object does not perform input argument validation;therefore the string returned from this method could be null.

Specified By getHelp in interface AmiMethodInterface

Returns The help text of this method.


AmiMethod.getIndexName()

Method

Declaration public java.lang.String[] getIndexName()


66/225


Declaration pub c ja a a g St g[] get de a e()

Purpose Returns the array containing the output parameters that serve as the index names.

Remarks The index name is required if this AMI method has the potential to returnmultiple rows of data.

Specified by The getIndexName in interface AmiMethodInterface

Returns Returns the array containing the index names of the method, if it has beenexplicitly specified, otherwise null.

AmiMethod.getName() |51

AmiMethod.getName()

Method

Declaration public final java.lang.String getName()


67/225


Purpose Returns the name of this method.

Remarks The constructor of this object does not perform input argument validation,therefore the string returned from this method could be null.

Specified by getName in interface AmiMethodInterface

Returns The name of this method.


AmiMethod.getReturns()

Method

Declaration public abstract AmiParameterList getReturns()


68/225


Purpose Returns an AmiParameterList object that describes the output return argumentsof this AMI method.

Remarks Subclasses of the AmiMethod class must implement this method for the purpose ofspecifying the method return arguments. If the AMI method does not have anyreturn arguments, then null should be returned.

AMI method of type AmiConstants.METHOD_TYPE_INFO andAmiConstants.METHOD_TYPE_ACTION_INFO must return a non-nullAmiParameterList with at least one AmiParameter.

Specified by getReturns in interface AmiMethodInterface

Returns

See Also AmiSession, page 14:

AmiSession.addMethod(), page 19


AmiParameterList Output returns descriptions.

AmiMethod.getSession() |53

AmiMethod.getSession()

Method

Declaration public final AmiSession getSession()


69/225


Purpose Returns the AmiSession object that this method belongs to.

Remarks Until this method is been added to an AMI session, the session object returnedfrom this method is null.

Specified By getSession in interface AmiMethodInterface

Returns The associated AMI session.


70/225

AmiMethod.getType() |55

AmiMethod.getType()

Method

Declaration public final AmiMethodType getType()


71/225


Purpose Returns the type object of this method.

Specified by getType in interface AmiMethodInterface

Returns The type object of this AMI method.

The returned type object is one of the following:

• AmiConstants.METHOD_TYPE_INFO

• AmiConstants.METHOD_TYPE_ACTION

• AmiConstants.METHOD_TYPE_ACTION_INFO

See Also AmiErrors, page 42

AmiConstants, page 41


AmiMethod.onInvoke()

Method

Declaration public abstract AmiParameterList

onInvoke(AmiParameterList arguments)


72/225


onInvoke(AmiParameterList arguments)throws java.lang.Exception

Purpose This method is invoked by the AMI Java API when a method invo

Tib Hawk Ami Java Reference

Documents

Transcript of Tib Hawk Ami Java Reference