TIBCO Hawk® AMI Java Reference
Software Release 4.9 November 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
Preface ...... ix Changes from the Previous Release of this Guide ...... x Related Documentation ...... xi TIBCO Hawk Documentation ...... xi Other TIBCO Product Documentation ...... xii Third-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() ...... 17 AmiSession.addMethod() ...... 19
TIBCO Hawk AMI Java Reference iv | Contents
AmiSession.addMethods()...... 20 AmiSession.announce()...... 21 AmiSession.getDisplayName() ...... 22 AmiSession.getHelp() ...... 23 AmiSession.getMaxThreads() ...... 24 AmiSession.getMethod() ...... 25 AmiSession.getMethods() ...... 26 AmiSession.getName() ...... 27 AmiSession.getRvQueue() ...... 28 AmiSession.getTrace()...... 29 AmiSession.sendData() ...... 30 AmiSession.sendUnsolicitedMsg() ...... 31 AmiSession.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() ...... 63 AmiAsyncMethod.onData() ...... 64
TIBCO Hawk AMI Java Reference Contents | v
AmiGetVersionMethod ...... 65 AmiGetVersionMethod.addComponentVersion() ...... 66 AmiGetVersionMethod.getArguments() ...... 67 AmiGetVersionMethod.getIndexName() ...... 68 AmiGetVersionMethod.getReturns()...... 69 AmiGetVersionMethod.onInvoke() ...... 70 AmiMethodContext ...... 71 AmiMethodContext.getMethod()...... 72 AmiMethodContext.getDuration() ...... 73 AmiMethodContext.getArguments() ...... 74 AmiMethodContext.getReplySubject() ...... 75 AmiMethodContext.getContext()...... 76 AmiMethodContext.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 ...... 99 AmiParameterList.AmiParameterList() ...... 100
Chapter 7 AMI Interfaces...... 101 AmiEnabledInterface ...... 102 AmiEnabledInterface.getMethods() ...... 104 AmiEnabledInterface.setSession() ...... 105 AmiMethodInterface ...... 106 AmiMethodInterface.getArguments() ...... 108
TIBCO Hawk AMI Java Reference vi | Contents
AmiMethodInterface.getHelp() ...... 109 AmiMethodInterface.getIndexName() ...... 110 AmiMethodInterface.getName()...... 111 AmiMethodInterface.getReturns() ...... 112 AmiMethodInterface.getSession() ...... 113 AmiMethodInterface.getTimeout() ...... 114 AmiMethodInterface.getType()...... 115 AmiMethodInterface.onInvoke() ...... 116 AmiMethodInterface.setIndexName() ...... 117 AmiMethodInterface.setSession() ...... 118 AmiAsyncMethodInterface ...... 119 AmiAsyncMethodInterface.onStart() ...... 120 AmiAsyncMethodInterface.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() ...... 146 AmiTraceInterface.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
TIBCO Hawk AMI Java Reference 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 ...... 166 Trace.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() ...... 196 AmiTrace.getMethods()...... 197 AmiTrace.logAlways() ...... 198 AmiTrace.logAmi() ...... 199 AmiTrace.logDebug() ...... 200 AmiTrace.logError()...... 201 AmiTrace.logInfo()...... 202 AmiTrace.logWarning() ...... 203 AmiTrace.setSession() ...... 204 TraceErrors ...... 205
TIBCO Hawk AMI Java Reference viii | Contents
HawkErrors ...... 206
Index ...... 207
TIBCO Hawk AMI Java Reference | ix Preface
This manual describes the TIBCO Hawk® Application Programming Interface (API) for Java programmers. The first part of this manual deals with the concepts involved in writing API programs for the TIBCO Hawk monitoring system. The following sections deal with the specific API programming components. 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 x • Related Documentation, page xi • Typographical Conventions, page xiii • Connecting with TIBCO Resources, page xv
TIBCO Hawk AMI Java Reference 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 documentation defects.
TIBCO Hawk AMI Java Reference 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 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.
TIBCO Hawk AMI Java Reference xii | Related Documentation
• TIBCO Hawk HTTP Adapter User’s Guide Contains information about performing discovery, monitoring of agent status, monitoring of agent alerts, method invocation, method subscription, and many more activities on TIBCO Hawk and third-party products. • TIBCO Hawk Enterprise Message Service Administrator Plug-in Microagent Reference Contains details about the microagent methods that are used to administer and monitor the TIBCO Enterprise Message Service server. • TIBCO Hawk Release Notes Read the release notes for a list of new and changed features. This document also contains lists of known issues and closed issues for this release.
Other TIBCO Product Documentation You may find it useful to read the documentation for the following TIBCO products: •TIBCO Rendezvous® — TIBCO Rendezvous Concepts — TIBCO Rendezvous Administration — TIBCO Rendezvous Configuration Tools • TIBCO Enterprise Message Service™ — TIBCO Enterprise Message Service Installation — TIBCO Enterprise Message Service User’s Guide • TIBCO Administator™ — TIBCO Administrator Installation Guide
Third-Party Documentation You may find the following third-party documentation useful. • The Java Language Specification by Gosling, Joy, and Steele
TIBCO Hawk AMI Java Reference Preface | xiii
Typographical Conventions
The following typographical conventions are used in this manual.
Table 1 General Typographical Conventions Convention Use Many TIBCO products CAN be installed within the same directory. This directory is referenced in documentation as TIBCO_HOME. The value of TIBCO_HOME TIBCO_HOME depends on the operating system. For example, on Windows systems, the default value is C:\tibco. Incompatible products and multiple instances of the same product should be installed into different installation environments.
CONFIG_FOLDER A TIBCO configuration folder stores configuration data generated by TIBCO products. Configuration data can include sample scripts, session data, configured binaries, logs, and so on. This folder is referenced in documentation as CONFIG_FOLDER. TIBCO Hawk installs into a directory within
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 Bold code font is used in the following ways: font • In procedures, to indicate what a user types. For example: Type admin. • In large code samples, to indicate the parts of the sample that are of particular interest. • In command syntax, to indicate the default parameter for a command. For example, if no parameter is specified, MyCommand is enabled: MyCommand [enable | disable]
TIBCO Hawk AMI Java Reference xiv | Typographical Conventions
Table 1 General Typographical Conventions (Cont’d) Convention Use
italic font Italic font is used in the following ways: • To indicate a document title. For example: See TIBCO BusinessWorks Concepts. • To introduce new terms For example: A portal page may contain several portlets. Portlets are mini-applications that run in a portal. • To indicate a variable in a command or code syntax that you must replace. For example: MyCommand pathname
Key Key name separated by a plus sign indicate keys pressed simultaneously. For combinations example: Ctrl+C. Key names separated by a comma and space indicate keys pressed one after the other. For example: Esc, Ctrl+Q.
The note icon indicates information that is of special interest or importance, for example, an additional action required only in certain circumstances.
The tip icon indicates an idea that could be useful, for example, a way to apply the information provided in the current section to achieve a specific result.
The warning icon indicates the potential for a damaging situation, for example, data loss or corruption if certain steps are taken or not taken.
TIBCO Hawk AMI Java Reference Preface | xv
Connecting with TIBCO Resources
How to Join TIBCOmmunity TIBCOmmunity is an online destinaton for TIBCO customers, partners, and resident experts—a place to share and access the collective experience of the TIBCO community. TIBCOmmunity offers forums, blogs, and access to a variety of resources. To register, go to http://www.tibcommunity.com.
How to Access All TIBCO Documentation After you join TIBCOmmunity, you can access the documentation for all supported product versions here: http://docs.tibco.com/TibcoDoc
How to Contact TIBCO Support For comments or problems with this manual or the software it addresses, please contact TIBCO Support as follows. • For an overview of TIBCO Support, and information about getting started with TIBCO Support, visit this site: http://www.tibco.com/services/support • If you already have a valid maintenance or support contract, visit this site: https://support.tibco.com Entry to this site requires a user name and password. If you do not have a user name, you can request one.
TIBCO Hawk AMI Java Reference xvi | Connecting with TIBCO Resources
TIBCO Hawk AMI Java Reference | 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 the appropriate section. Class and interface descriptions, summary tables, and detailed member descriptions are given. Methods within the classes and interfaces 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
TIBCO Hawk AMI Java Reference 2 | Chapter 1 Introduction
The AMI Protocol
The TIBCO Hawk Application Management Interface (AMI) protocol is a specification of TIBCO Rendezvous messages that define the interactions between an AMI manager and an AMI application. An AMI manager is any application that monitors or manages AMI applications, or both, via the AMI protocol. A TIBCO Hawk agent is an example of an AMI manager. An AMI application exposes internal methods that allow AMI managers to manage and monitor that application by exchanging data and events with it. You should first read and understand the discussion of the AMI protocol in the TIBCO Hawk Programmer’s Guide before attempting to use the AMI Java API described in this manual.
TIBCO Hawk AMI Java Reference The TIBCO Hawk AMI Java API | 3
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 development easier and more foolproof because it takes care of all the AMI and TIBCO Rendezvous protocol details for you. The API also ensures that your application will 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 interaction with an AMI manager. The AmiSession class provides an AMI session with methods to create the session, announce it, and to exchange data, events, and errors with the AMI session.
The AmiMethod Class An AMI application consists of a set of AMI methods that can be invoked by an AMI manager. The AmiMethod class encapsulates the definition and processing of these AMI methods. The method class provides methods to create, and process invocations of your AMI methods. AmiMethod objects are created and added to your AMI session objects. The AMI session announces method objects (sends their descriptions to an AMI manager) and detects invocations of your AMI methods. The AMI session object invokes your methods by means of the onInvoke() method of the AMI method class.
The AmiAsyncMethod Class
The AmiAsyncMethod class implements asynchronous AMI methods, so that data can be returned to an AMI manager as soon as it becomes available. In a typical scenario, when the manager requires data, it polls the method by means of a synchronous data call. The AmiAsyncMethod class allows data to be returned asynchronously, 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 eliminates polling and allows the manager to also be event-driven, with respect to this method'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 also inform it when it no longer has an interest in the data.
TIBCO Hawk AMI Java Reference 4 | Chapter 1 Introduction
The manager can have several subscriptions. Each subscription is represented by a unique context. The application receives this unique context along with the input parameters for each subscription. The tracking of each context and its associated input parameters is done by the AmiSession. The application is no longer responsible for the tracking of contexts.
The AmiParameter and AmiParameterList Classes
During an invocation, an AmiMethod object receives input parameters and returns output parameters. The AmiParameter class encapsulates a single input or output parameter. 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 specifying multiple instances of its output parameters during a method invocation. A method that returns tabular data must define one or more indexes to uniquely index each row. An index is specified by the name(s) of the output parameters whose values form the index.
The AmiParameterList class is used to group AmiParameter objects to define a complete 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 for your AMI session. The AmiTrace class provides methods to configure and log messages 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 not supported. Use of these characters results in an error.
TIBCO Hawk AMI Java Reference AMI Java API Sample Programs | 5
AMI Java API Sample Programs
The TIBCO Hawk software distribution includes sample AMI Java API programs that will help you to better understand how to use the API. These samples can be found in the directory
TIBCO Hawk AMI Java Reference 6 | Chapter 1 Introduction
TIBCO Hawk AMI Java Reference | 7
Chapter 2 Programmer’s Checklist
The TIBCO Hawk Java API provides a set of class packages implemented by the TIBCO Hawk AMI, to be used as components in building applications for the TIBCO Hawk monitoring system and invoking methods on the objects implemented by the classes.
Topics
• Programmer’s Checklist, page 8
TIBCO Hawk AMI Java Reference 8 | Chapter 2 Programmer’s Checklist
Programmer’s Checklist
Install Install the latest TIBCO Hawk software and TIBCO Rendezvous software releases. We recommend using Java 1.3.1 to compile and run your AMI application.
Code Your AMI Java source code file must contain the following imports. • com.tibco.tibrv.* • COM.TIBCO.hawk.ami.*
Compile
While compiling your AMI Java application, your CLASSPATH must include ami.jar and utilities.jar from TIBCO Hawk Java directory and tibrvj.jar from the TIBCO Rendezvous Java directory.
Run
While running your AMI Java application, your CLASSPATH must include ami.jar and utilities.jar from the TIBCO Hawk Java directory and tibrvj.jar from the TIBCO Rendezvous /lib directory.
TIBCO Hawk AMI Java Reference | 9
Chapter 3 Java Classes and Class Structure
This chapter provides a diagram showing organization of the TIBCO Hawk AMI API Java classes.
Topics
• Class Hierarchy, page 10 • Interface Hierarchy, page 11
TIBCO Hawk AMI Java Reference 10 | Chapter 3 Java Classes and Class Structure
Class Hierarchy
The general hierarchy for Java class objects is as follows:
Classes under java.lang.object:
java.util.AbstractCollection java.util.AbstractList java.util.Vector COM.TIBCO.hawk.ami., AmiParameterList COM.TIBCO.hawk.ami.AmiParameterList COM.TIBCO.hawk.ami.AmiAlertType COM.TIBCO.hawk.ami.AmiConstants COM.TIBCO.hawk.ami.AmiErrors COM.TIBCO.hawk.ami.AmiMethod COM.TIBCO.hawk.ami.AmiAsyncMethod COM.TIBCO.hawk.ami.AmiGetVersionMethod COM.TIBCO.hawk.ami.AmiMethodContext COM.TIBCO.hawk.ami.AmiMethodType COM.TIBCO.hawk.ami. AmiParameter COM.TIBCO.hawk.ami.AmiSession COM.TIBCO.hawk.ami.ComponentVersion COM.TIBCO.hawk.utilities.exception.HawkErrors CCOM.TIBCO.hawk.utilities.exception.HawkErrors java.lang.Throwable java.lang.Exception COM.TIBCO.hawk.utilities.exception.HawkException COM.TIBCO.hawk.ami.AmiException COM.TIBCO.hawk.utilities.trace.TraceException COM.TIBCO.hawk.utilities.trace.Trace COM.TIBCO.hawk.ami.AmiTrace COM.TIBCO.hawk.ami.AmiTraceInterface COM.TIBCO.hawk.utilities.trace.TraceErrors
TIBCO Hawk AMI Java Reference Interface Hierarchy | 11
Interface Hierarchy
The following diagram shows the interface hierarchy under java.lang.object.
COM.TIBCO.hawk.utilities.trace.Trace
COM.TIBCO.hawk.ami.AmiTrace COM.TIBCO.hawk.ami.AmiTraceInterface COM.TIBCO.hawk.ami.AmiEnabledInterface COM.TIBCO.hawk.ami.AmiMethodInterface COM.TIBCO.hawk.ami.AmiAsyncMethodInterface COM.TIBCO.hawk.ami.AmiParameterList
TIBCO Hawk AMI Java Reference 12 | Chapter 3 Java Classes and Class Structure
TIBCO Hawk AMI Java Reference | 13
Chapter 4 Java AmiSession Class
This chapter outlines the TIBCO Hawk AMI API Java Session class. The AmiSession class handles the interface between the Java application programming 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
TIBCO Hawk AMI Java Reference 14 | Chapter 4 Java AmiSession Class
AmiSession Class Class under java.lang.Object:
COM.TIBCO.hawk.ami.AmiSession
Declaration public class AmiSession extends java.lang.Object implements AmiEnabledInterface
Purpose The AmiSession class and its supporting class objects provide a Java application programming interface (API), which implements the AMI protocol in Java language.
Remarks Applications instrumented with TIBCO Hawk AMI define a set of synchronous methods (AmiMethodInterface), and/or asynchronous methods (AmiAsyncMethodInterface), through which the application is monitored and managed by TIBCO Hawk software. Applications instrumented with TIBCO Hawk software function as a TIBCO Hawk Microagent.
An AmiSession object must be identified by a unique name, with an optional help text to describe the functionality of the application.
Fields public static final int DEFAULT_MAX_THREADS public static final int MAX_MAX_THREADS
Field Summary Field Meaning DEFAULT_MAX_THREADS The default maximum number of invocation processing threads this AmiSession is to create. This default maximum is currently set to 1.
MAX_MAX_THREADS The maximum number of invocation processing threads this AmiSession is allowed to create. This maximum number is currently set to 9.
TIBCO Hawk AMI Java Reference AmiSession | 15
Member Member Description Page Summary AmiSession() Constructor. 17
Methods to Add Interface Objects
AmiSession.addMethod() Adds the specified 19 AmiMethodInterface object to this AmiSession.
AmiSession.addMethods() Adds the array of methods defined 20 by the specified AmiEnabledInterface object to this session.
Discovery Method
AmiSession.announce() Send the discovery message to the 21 TIBCO Hawk agent.
Stop Method
AmiSession.stop() Stops the AMI session. 33
Accessor Methods
AmiSession.getHelp() Returns the help text for this AMI 23 session.
AmiSession.getMaxThreads() Returns the maximum number of 24 invocation processing threads this AmiSession is allowed to create.
AmiSession.getMethod() Retrieve the 25 AmiMethodInterface object by its name.
AmiSession.getMethods() Returns an array of 26 AmiMethodInterfaces for getting and setting AMI session's number of threads.
AmiSession.getName() Returns the name of this AMI 27 session.
AmiSession.getRvQueue() Returns the RvQueue used to create 28 this AmiSession.
TIBCO Hawk AMI Java Reference 16 | Chapter 4 Java AmiSession Class
Member (Cont’d) Description (Cont’d) Page
AmiSession.getTrace() Returns the AmiTraceInterface 28 object used to create this AmiSession.
Methods to Send Data
AmiSession.sendData() Sends data to subscriber according 30 to the specified method subscription context.
AmiSession.sendUnsolicitedMsg() The method sends unsolicited 31 message to TIBCO Hawk agent to be processed by rulebases via the onUnsolicitedMsg() method
Methods to Set Parameters
AmiSession.setMaxThreads() Sets the maximum number of 32 invocation processing thread this AmiSession is allowed to create.
AmiSession.createCommonMethods() Creates the following methods for 34 the AmiSession: getReleaseVersion getTraceLevel setTraceLevel getTraceParameters setTraceParameters
See Also AmiSession.getMaxThreads(), page 24 AmiSession.sendData(), page 30
TIBCO Hawk AMI Java Reference AmiSession() | 17
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 the AmiTraceInterface interface.
Parameters Parameter Description
rvTransport The TibrvTransport object.
rvQueue The TibrvQueue object.
TIBCO Hawk AMI Java Reference 18 | Chapter 4 Java AmiSession Class
Parameter Description
amiSessionName Name to uniquely identify this amiSession as a TIBCO Hawk microagent. Cannot be null or an empty string.
amiSessionDisplay User-friendly name string for microagent.
amiSessionHelp Help text for describing the functionality of this TIBCO Hawk microagent.
service Specifies which User Datagram Protocol (UDP) service group the TIBCO Rendezvous daemon should use for session communications. The default configuration uses the service port number 7474. A service can be specified either by its name or its port number.
network Specifies what network to use for outbound session communications when a computer is connected to more than one network. A network can be specified by its name or by its IP address. This parameter is also used to specify the multicast groups to use for communication.
daemon Specifies which TIBCO Rendezvous daemon is to handle communication for the session. A local daemon is specified by the communications type (always tcp) and a socket number (e.g., 7474). The default configuration uses the local daemon with the TCP socket number 7474.
trace An instance of the AmiTraceInterface implementation.
See Also AmiTraceInterface, page 122 AmiTrace, page 194
TIBCO Hawk AMI Java Reference AmiSession.addMethod() | 19
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 AMI method. AmiException is thrown if the AMI method does not comply with the following 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 each input/output parameter list. • All method parameter must be specified with a sample value.
• If the method type is AmiConstants.METHOD_TYPE_INFO or AmiConstants.METHOD_TYPE_ACTION_INFO, then its getReturns() method must return a non-null and non-empty AmiParameterList object. • If the method returns multiple rows of data, it must specify an index parameter name. The index parameter name must exist in its return AmiParameterList.
Parameters Parameter Description
method The method to be added to this AmiSession.
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.
TIBCO Hawk AMI Java Reference 20 | Chapter 4 Java AmiSession Class
AmiSession.addMethods() Method
Declaration public void addMethods(AmiEnabledInterface amiEnabled) throws AmiException
Purpose Adds the array of methods defined by the specified AmiEnabledInterface object to this session.
Remarks This method first invokes the AmiEnabledInterface.setSession() method of the specified AMI-enabled object, using the current AMI session. Then, the array of AmiMethodInterface is obtained through its AmiEnabledInterface.getMethods() method. This method then adds each AmiMethodInterface object to this AMI session.
AmiMethodInterface validation rules for this method are the same as those for AmiSession.addMethod(AmiMethodInterface).
Parameters Parameter Description
amiEnabled An object that implements the AmiEnabledInterface interface.
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
TIBCO Hawk AMI Java Reference AmiSession.announce() | 21
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 add new 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.
TIBCO Hawk AMI Java Reference 22 | Chapter 4 Java AmiSession Class
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.
TIBCO Hawk AMI Java Reference AmiSession.getHelp() | 23
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.
TIBCO Hawk AMI Java Reference 24 | Chapter 4 Java AmiSession Class
AmiSession.getMaxThreads() Method
Declaration public int getMaxThreads()
Purpose Returns the maximum number of invocation processing thread this AMI session is allowed to create.
Returns The maximum number of invocation processing threads.
TIBCO Hawk AMI Java Reference AmiSession.getMethod() | 25
AmiSession.getMethod() Method
Declaration public AmiMethodInterface getMethod( java.lang.String methodName) throws AmiException
Purpose Retrieve the AmiMethodInterface object by its name.
Parameters Parameter Description
methodName Name of the method to retrieve.
Returns AmiMethodInterface corresponding to the specified name. If no method object is known by this name, then null is returned.
Throws AmiException is thrown if methodName is null.
TIBCO Hawk AMI Java Reference 26 | Chapter 4 Java AmiSession Class
AmiSession.getMethods() Method
Declaration public AmiMethodInterface[] getMethods() throws AmiException
Purpose Returns an array of AmiMethodInterface objects for getting and setting the AMI session’s number of threads.
Remarks This method implements the AmiEnabledInterface such that an array of two AmiMethodInterfaces for getting and setting the number of AMI invocation processing 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 or setMaxThreads.
TIBCO Hawk AMI Java Reference AmiSession.getName() | 27
AmiSession.getName() Method
Declaration public java.lang.String getName()
Purpose Returns the name of this AMI session.
Returns String representing the AMI session name.
TIBCO Hawk AMI Java Reference 28 | Chapter 4 Java AmiSession Class
AmiSession.getRvQueue() Method
Declaration public com.tibco.tibrv.TibrvQueue getRvQueue()
Purpose Returns the TibrvQueue object used to create this AMI session.
Returns TibrvQueue
TIBCO Hawk AMI Java Reference AmiSession.getTrace() | 29
AmiSession.getTrace() Method
Declaration public AmiTraceInterface getTrace()
Purpose Returns the AmiTraceInterface object used to create this AmiSession.
Returns AmiTraceInterface
See Also AmiTraceInterface, page 122
TIBCO Hawk AMI Java Reference 30 | Chapter 4 Java AmiSession Class
AmiSession.sendData() Method
Declaration public final void sendData( AmiMethodContext context, AmiParameterList data) throws AmiException
Purpose Sends data to the subscriber, according to the specified method subscription context.
Remarks When data from an AMI asynchronous method becomes available, this method allows the application to publish the data. This method is called by AmiAsyncMethod.onData().
Parameters Parameter Description context The context associated with a particular subscription to which data is to be sent.
data The data to be published.
Throws AmiException is thrown if incorrect data is passed or if the publication fails.
See Also AmiMethodContext, page 71
TIBCO Hawk AMI Java Reference AmiSession.sendUnsolicitedMsg() | 31
AmiSession.sendUnsolicitedMsg() 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 be processed by rulebases using the onUnsolicitedMsg() method.
Parameters Parameter Description
type Type of the unsolicited message.
text User-defined text message.
id Message id.
Throws AmiException is thrown if incorrect data has been passed or if the AMI object was unable to send a message to the TIBCO Hawk agent.
See Also AmiConstants, page 41
TIBCO Hawk AMI Java Reference 32 | Chapter 4 Java AmiSession Class
AmiSession.setMaxThreads() Method
Declaration public void setMaxThreads(int max) throws AmiException
Purpose Sets the maximum number of invocation processing threads this AmiSession is allowed to create.
Parameters Parameter Description
max Maximum number of invocation processing threads.
Throws AmiException is thrown if the specified maximum value is less than one (1) or greater than MAX_MAX_THREADS
See Also AmiSession(), page 17
TIBCO Hawk AMI Java Reference AmiSession.stop() | 33
AmiSession.stop() Method
Declaration public void stop() throws AmiException
Purpose Stops the AMI session. All associated Hawk agents are notified that this AMI session is no longer running or supported. These agents will remove the associated microagent from their microagent lists. This AMI session will be inactive until AmiSession.announce() is called to re-activate this session.
Throws AmiException is thrown if this method fails to stop the AMI session.
TIBCO Hawk AMI Java Reference 34 | Chapter 4 Java AmiSession Class
AmiSession.createCommonMethods() Method
Declaration public void createCommonMethods(String inName, String inVersion, String inDate, int inMajorVersion, int inMinorVersion, int inUpdateVersion) throws AmiException
Purpose Creates the following methods for the ami_Session: — getReleaseVersion — getTraceLevel — setTraceLevel — getTraceParameters — setTraceParameters
Parameter Parameter Description
amiSession The handle to the current ami_Session object. If ami_SessionCreate() fails, you can supply NULL since the session has not been created.
inVersionName Release version name of application
inVersion Release version of application
inVersionDate Release version date of application
inVersionMajor Major version
inVersionMinor Minor version
inVersionUpdate Update Version
TIBCO Hawk AMI Java Reference | 35
Chapter 5 AMI Classes
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
TIBCO Hawk AMI Java Reference 36 | Chapter 5 AMI Classes
AmiAlertType Class 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 this class are available in the AmiConstants class. These are: AmiConstants.ALERT_TYPE_INFO AmiConstants.ALERT_TYPE_WARNING AmiConstants.ALERT_TYPE_ERROR
Method Method Description Page Summary AmiAlertType.toString() Returns the string representation of the 37 AMI alert type object.
AmiAlertType.fromString() Returns the type object according to the 38 input type string.
AmiAlertType.equals() Determines whether the specified alert 39 type is equivalent with this object.
AmiAlertType.hashCode() Returns a hash code value for the 40 object.
TIBCO Hawk AMI Java Reference AmiAlertType.toString() | 37
AmiAlertType.toString() Method
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
TIBCO Hawk AMI Java Reference 38 | Chapter 5 AMI Classes
AmiAlertType.fromString() Method
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.
TIBCO Hawk AMI Java Reference AmiAlertType.equals() | 39
AmiAlertType.equals() Method
Declaration public boolean equals(AmiAlertType type)
Purpose Determines whether the specified method type is equivalent with this object.
Parameters Parameter Description type AMI method type.
Returns True if the two objects are equivalent. False otherwise.
TIBCO Hawk AMI Java Reference 40 | Chapter 5 AMI Classes
AmiAlertType.hashCode() Method
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
TIBCO Hawk AMI Java Reference AmiConstants | 41
AmiConstants Class 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_INFO public static final AmiMethodType METHOD_TYPE_ACTION public static final AmiMethodType METHOD_TYPE_ACTION_INFO public static final AmiAlertType ALERT_TYPE_INFO public static final AmiAlertType ALERT_TYPE_WARNING public static final AmiAlertType ALERT_TYPE_ERROR
Field Summary Member Description VERSION TIBCO Hawk AMI version. This API currently implements the TIBCO Hawk AMI Protocol 1.2 specification
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-defined actions 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.
TIBCO Hawk AMI Java Reference 42 | Chapter 5 AMI Classes
AmiErrors Class 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 the COM.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 public static final int AMI_INVALID_OPERATION_ERR Declarations public static final int AMI_METHOD_FORMAT_ERR public static final int AMI_REPLY_ERR public 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 format error occurred.
AMI_REPLY_ERROR Error code to indicate that a reply error occurred.
AMI_RV_ERROR Error code to indicate that a TIBCO Rendezvous error occurred.
TIBCO Hawk AMI Java Reference AmiMethod | 43
AmiMethod Class COM.TIBCO.hawk.ami.AmiMethod AmiAsyncMethod AmiGetVersionMethod
Declaration public abstract class AmiMethod extends java.lang.Object implements AmiMethodInterface
Purpose Implements the AmiMethodInterface as an abstract class.
Remarks Classes that extend from this AmiMethod abstract class must implement the following methods: • AmiMethod.getArguments() • AmiMethod.getReturns() • AmiMethod.onInvoke()
Member Method Description Page Summary AmiMethod.AmiMethod() Constructor 45
AmiMethod.equals() Compares if the specified AMI method is 47 equivalent of this AMI method.
AmiMethod.getArguments() Returns an AmiParameterList that 48 describes the input arguments of this AMI method.
AmiMethod.getHelp() Return the help text of the method. 49
AmiMethod.getIndexName() Returns the name of the output 50 parameter that serves as the index name.
AmiMethod.getName() Return the name of this method. 51
AmiMethod.getReturns() Returns an AmiParameterList that 52 serves to describe the output return arguments of this AMI method.
AmiMethod.getSession() Returns the AmiSession object that this 53 method belongs to.
TIBCO Hawk AMI Java Reference 44 | Chapter 5 AMI Classes
Method Description Page AmiMethod.getTimeout() Returns the timeout interval of this AMI 54 method.
AmiMethod.getType() Return the type object of this AMI 55 method.
AmiMethod.onInvoke() This method is invoked by the AMI Java 57 API when a method invocation arrives from the managing TIBCO Hawk agent.
AmiMethod.setIndexName() Sets the AMI method's index parameter 57 name.
AmiMethod.setSession() Sets the AmiSession for this method. 58
TIBCO Hawk AMI Java Reference AmiMethod.AmiMethod() | 45
AmiMethod.AmiMethod() Constructor
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 timeout java.lang.String [] indexName)
Purpose Constructor for creating an instance of AmiMethod object.
• The first form creates an AmiMethod with no index (method does not return multiple rows of data).
• The second form allows the user to create an AmiMethod with a specific index for the purpose of returning multiple rows of data in one single constructor, as opposed to creating the method, then using the setIndexName() method to set the index.
TIBCO Hawk AMI Java Reference 46 | Chapter 5 AMI Classes
• The second form allows the user to create an AmiMethod with a composite index for the purpose of returning multiple rows of data in one single constructor.
Remarks This constructor does not perform input argument validation. Validation is performed only with AmiSession.addMethod.
Parameters Parameter Description name Name of method.
help Help text of method.
type Type of method. The type parameter must be one of the following: 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 microagent if it does not receive any response from the microagent within the time specified in the timeout field.
indexName AMI method parameter that serves as the index.
See Also AmiSession, page 14 AmiTraceInterface.getLevelString(), page 132 AmiErrors, page 42, AmiConstants, page 41
TIBCO Hawk AMI Java Reference AmiMethod.equals() | 47
AmiMethod.equals() Method
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 method names.
Parameters Parameter Description method Method to compare.
Returns True if the specified method is equivalent to this method, otherwise false.
TIBCO Hawk AMI Java Reference 48 | Chapter 5 AMI Classes
AmiMethod.getArguments() Method
Declaration public abstract AmiParameterList getArguments()
Purpose Returns an AmiParameterList that describes the input arguments of this AMI method.
Remarks Subclasses of the AmiMethod class must implement this method for the purpose of returning the method input arguments specification. If the AMI method does not have any input arguments, then null is returned.
Specified by getArguments in interface AmiMethodInterface
Returns Input arguments of this AMI method.
TIBCO Hawk AMI Java Reference AmiMethod.getHelp() | 49
AmiMethod.getHelp() Method
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.
TIBCO Hawk AMI Java Reference 50 | Chapter 5 AMI Classes
AmiMethod.getIndexName() Method
Declaration public java.lang.String[] getIndexName()
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 return multiple rows of data.
Specified by The getIndexName in interface AmiMethodInterface
Returns Returns the array containing the index names of the method, if it has been explicitly specified, otherwise null.
TIBCO Hawk AMI Java Reference AmiMethod.getName() | 51
AmiMethod.getName() Method
Declaration public final java.lang.String getName()
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.
TIBCO Hawk AMI Java Reference 52 | Chapter 5 AMI Classes
AmiMethod.getReturns() Method
Declaration public abstract AmiParameterList getReturns()
Purpose Returns an AmiParameterList object that describes the output return arguments of this AMI method.
Remarks Subclasses of the AmiMethod class must implement this method for the purpose of specifying the method return arguments. If the AMI method does not have any return arguments, then null should be returned.
AMI method of type AmiConstants.METHOD_TYPE_INFO and AmiConstants.METHOD_TYPE_ACTION_INFO must return a non-null AmiParameterList with at least one AmiParameter.
Specified by getReturns in interface AmiMethodInterface
Returns Parameter Description AmiParameterList Output returns descriptions.
See Also AmiSession, page 14:
AmiSession.addMethod(), page 19
TIBCO Hawk AMI Java Reference AmiMethod.getSession() | 53
AmiMethod.getSession() Method
Declaration public final AmiSession getSession()
Purpose Returns the AmiSession object that this method belongs to.
Remarks Until this method is been added to an AMI session, the session object returned from this method is null.
Specified By getSession in interface AmiMethodInterface
Returns The associated AMI session.
TIBCO Hawk AMI Java Reference 54 | Chapter 5 AMI Classes
AmiMethod.getTimeout() Method
Declaration public int getTimeout()
Purpose Returns the timeout period for this AMI method.
Specified By getTimeout in interface AmiMethodInterface.
Returns The timeout value of this method, in milliseconds.
TIBCO Hawk AMI Java Reference AmiMethod.getType() | 55
AmiMethod.getType() Method
Declaration public final AmiMethodType getType()
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
TIBCO Hawk AMI Java Reference 56 | Chapter 5 AMI Classes
AmiMethod.onInvoke() Method
Declaration public abstract AmiParameterList onInvoke(AmiParameterList arguments) throws java.lang.Exception
Purpose This method is invoked by the AMI Java API when a method invocation arrives from the managing TIBCO Hawk agent.
Specified by onInvoke in interface AmiMethodInterface
Parameters Parameter Description arguments Input arguments of the method invocation
Returns Parameter Description
AmiParameterList As the result of this AmiMethodInterface invocation.
Throws java.lang.Exception The application is allowed to throw any Exception object from this method, when the AMI API uses the text message of the Exception as the method invocation reply.
An AmiException thrown from this method is captured by the AMI Java API and is turned into an error reply. This error reply is sent back to the invoking agent as the result of the method invocation.
TIBCO Hawk AMI Java Reference AmiMethod.setIndexName() | 57
AmiMethod.setIndexName() Method
Declaration public void setIndexName(java.lang.String indexName)
Purpose Sets the AMI method's index parameter name.
Specified by setIndexName in interface AmiMethodInterface
Parameters Parameter Description indexName Name of the parameter that serves as the index.
TIBCO Hawk AMI Java Reference 58 | Chapter 5 AMI Classes
AmiMethod.setSession() Method
Declaration public final void setSession(AmiSession ami) throws AmiException
Purpose Sets the AmiSession for this method.
Remarks The application should not directly invoke this method to set the session. Instead, use AmiSession.addMethod(AmiMethodInterface) to associate this method with the desired AmiSession object. If the application invokes this method directly, and then attempts to perform AmiSession.addMethod on this method, the AmiSession operation throws an AmiException.
Specified by setSession in interface AmiMethodInterface
Parameters Parameter Definition
ami The AmiSession to be associated.
Throws AmiException is thrown if this method has been previously associated with another AmiSession.
TIBCO Hawk AMI Java Reference AmiAsyncMethod | 59
AmiAsyncMethod Class AmiMethod AmiAsyncMethod AmiGetVersionMethod
Definition public abstract class AmiAsyncMethod extends AmiMethod implements AmiAsyncMethodInterface
Purpose The AmiAsyncMethod is the default implementation of the AmiAsyncMethodInterface provided by this AMI Java API implementation as a convenient abstract class of the AmiAsyncMethodInterface.
Users of this AmiAsyncMethod class must implement the following abstract methods: • AmiAsyncMethod.onStart(), page 62 • AmiAsyncMethod.onStop(), page 63
Member Member Purpose Page Summary AmiAsyncMethod.AmiAsyncMe Constructor 60 thod()
AmiAsyncMethod.onStart() This method is invoked by the AMI Java 62 API when an interest, or subscription, on this asynchronous method arrives.
AmiAsyncMethod.onStop() This method is invoked by the AMI Java 63 API when the interest on this asynchronous method no longer exists.
AmiAsyncMethod.onData() This methods sends the data returned by 64 the onInvoke() method to all the subscribers.
Methods inherited from class COM.TIBCO.hawk.ami.AmiMethod
equals, getArguments, getHelp, getIndexName, getName, getReturns, getSession, getType, onInvoke, setIndexName, setSession
TIBCO Hawk AMI Java Reference 60 | Chapter 5 AMI Classes
AmiAsyncMethod.AmiAsyncMethod() Constructor
Definition public AmiAsyncMethod( java.lang.String name, java.lang.String help, AmiMethodType type)
public AmiAsyncMethod( java.lang.String name, java.lang.String help, AmiMethodType type, java.lang.String indexName)
public AmiAsyncMethod( java.lang.String name, java.lang.String help, AmiMethodType type, java.lang.String[] indexName)
public AmiAsyncMethod( java.lang.String name, java.lang.String help, AmiMethodType type, int timeout)
public AmiAsyncMethod( java.lang.String name, java.lang.String help, AmiMethodType type, int timeout, java.lang.String indexName)
public AmiAsyncMethod( java.lang.String name, java.lang.String help, AmiMethodType type, int timeout, java.lang.String[] indexName)
Purpose Constructor to create an asynchronous AMI method. • The first form creates an asynchronous AMI method. • The second form creates an asynchronous AMI method using a specific index.
Remarks This constructor does not make any effort to perform input argument validation. Validation is performed only at AmiSession.addMethod. For the method type parameter, use one of the following: • AmiConstants.METHOD_TYPE_INFO
• AmiConstants.METHOD_TYPE_ACTION
TIBCO Hawk AMI Java Reference AmiAsyncMethod.AmiAsyncMethod() | 61
• AmiConstants.METHOD_TYPE_ACTION_INFO
Parameters Parameter Description name Name of the method.
help Help text of the method.
type Type of the method.
indexName AMI method parameter name that serves as the index.
timeout Timeout of the method.
See Also AmiSession, page 14: AmiSession.addMethod()
AmiTraceInterface.getLevelString(), page 132
AmiErrors, page 42
AmiConstants, page 41
TIBCO Hawk AMI Java Reference 62 | Chapter 5 AMI Classes
AmiAsyncMethod.onStart() Method
Declaration public void onStart( AmiMethodContext context, AmiParameterList args) throws java.lang.Exception
Purpose This method is invoked by the AMI Java API when an interest or subscription on this asynchronous method arrives.
Specified by onStart in interface AmiAsyncMethodInterface
Parameters Parameter Purpose context The context associated with the subscription.
args The start subscription input arguments.
Throws java.lang.Exception An exception is thrown if incorrect data has been passed or the AmiSession object was unable to send the data.
TIBCO Hawk AMI Java Reference AmiAsyncMethod.onStop() | 63
AmiAsyncMethod.onStop() Method
Declaration public void onStop( AmiMethodContext context, AmiParameterList args) throws java.lang.Exception
Purpose This method is invoked by the AMI Java API when the interest in this asynchronous method no longer exists.
Specified By onStop in interface AmiAsyncMethodInterface
Parameters Parameter Description context The context associated with the subscription.
args The stop subscription input arguments.
Throws java.lang.Exception
TIBCO Hawk AMI Java Reference 64 | Chapter 5 AMI Classes
AmiAsyncMethod.onData() Method
Declaration public void onData() throws AmiException
Purpose This method calls AmiSession.sendData() to send data returned by the onInvoke() method to all the subscribers. The onInvoke() method can take varying actions depending on the input parameters. It is the user’s responsibility to call onData() when the event occurs. As the data depends on the input arguments, it is the user’s responsibility to handle the returned data appropriately. Usually, the application does not override this method.
Specified By onData in interface AmiAsyncMethodInterface
Throws AmiException
TIBCO Hawk AMI Java Reference AmiGetVersionMethod | 65
AmiGetVersionMethod Class AmiMethod AmiAsyncMethod AmiGetVersionMethod
Description public class AmiGetVersionMethod extends AmiMethod implements AmiMethodInterface
Purpose AmiGetVersionMethod implements the AmiMethodInterface to provide a synchronous AMI method that allows the monitoring TIBCO Hawk agent to query for information from the component version. By default, the current AMI library version information is returned. If the application uses other components that carry their own version information, the component version can be added into the AmiGetVersionMethod object for return by calling the AmiGetVersionMethod.addComponentVersion(Component) method.
Method Method Description Page Summary AmiGetVersionMethod.add Add new component version information to 66 ComponentVersion() be returned from this AMI method.
AmiGetVersionMethod.get Returns the input parameter list for this AMI 67 Returns() method.
AmiGetVersionMethod.getI Returns the index name of this AMI method. 68 ndexName()
AmiGetVersionMethod.get Returns the output parameter list for this AMI 69 Returns() method.
AmiGetVersionMethod.onI The callback method for the 70 nvoke() AmiGetVersionMethod object.
Methods inherited from class COM.TIBCO.hawk.ami.AmiMethod
equals, getHelp, getName, getSession, getType, setIndexName, setSession
TIBCO Hawk AMI Java Reference 66 | Chapter 5 AMI Classes
AmiGetVersionMethod.addComponentVersion() Method
Declaration public void addComponentVersion( COM.TIBCO.hawk.util.release.Component componentVersion)
Purpose Add new component version information to be returned from this AMI method.
Parameters Parameter Description componentVersion A component version object that implements the Component interface.
TIBCO Hawk AMI Java Reference AmiGetVersionMethod.getArguments() | 67
AmiGetVersionMethod.getArguments() Method
Declaration public AmiParameterList getArguments()
Purpose Returns the input parameter list for this AMI method.
Specified by getArguments() in interface AmiMethodInterface
Returns Parameter Description AmiParameterList Input parameter list.
Overrides getArguments() in class AmiMethod
TIBCO Hawk AMI Java Reference 68 | Chapter 5 AMI Classes
AmiGetVersionMethod.getIndexName() Method
Declaration public java.lang.String getIndexName()
Purpose Returns the index name of this AMI method.
Specified by getIndexName() in interface AmiMethodInterface
Returns The parameter index name.
Overrides getIndexName() in class AmiMethod
TIBCO Hawk AMI Java Reference AmiGetVersionMethod.getReturns() | 69
AmiGetVersionMethod.getReturns() Method
Declaration public AmiParameterList getReturns()
Purpose Returns the output parameter list for this AMI method.
Specified by getReturns() in interface AmiMethodInterface
Returns The AmiParameterList object containing the output parameter list.
Overrides getReturns() in class AmiMethod
TIBCO Hawk AMI Java Reference 70 | Chapter 5 AMI Classes
AmiGetVersionMethod.onInvoke() Method
Declaration public AmiParameterList onInvoke(AmiParameterList args) throws AmiException
Purpose The callback method for the AmiGetVersionMethod object.
Remarks This method can return multiple rows of component version information, listed one row per component.
Specified by onInvoke() in interface AmiMethodInterface
Parameters Parameter Description args Input arguments.
Returns The AmiParameterList object containing the list of component version information.
Overrides onInvoke() in class AmiMethod
TIBCO Hawk AMI Java Reference AmiMethodContext | 71
AmiMethodContext Class AmiMethodContext
Definition public class AmiMethodContext extends java.lang.Object
Purpose AmiMethodContext encapsulates the context of a method invocation or subscription. This enables AMI synchronous or asynchronous methods to reply to invocations or to publish data to its subscribers. No public constructor is available to the user of the AMI Java API. Instances of this class can only be created internally by the AMI Java API. Each time a new invocation or new subscription arrives, a new instance of this class is created by the AMI Java API and passed to the application.
Method Method Purpose Page Summary AmiMethodContext.getMethod() Returns the AMI method object 72 associated with this invocation or subscription.
AmiMethodContext.getDuration() Returns the DURATION parameter of 73 the asynchronous method subscription.
AmiMethodContext.getArgument Returns the input arguments of the 74 s() method invocation or subscription.
AmiMethodContext.getReplySubj Returns the reply subject of the method 75 ect() invoker or subscriber.
AmiMethodContext.getContext() Returns this method 76 invocation/subscription context number.
AmiMethodContext.equals() Tests whether the specified 77 AmiMethodContext is equivalent to this object.
AmiMethodContext.hashCode() Returns a hash code value for the 78 object.
TIBCO Hawk AMI Java Reference 72 | Chapter 5 AMI Classes
AmiMethodContext.getMethod() Method
Declaration public AmiMethodInterface getMethod()
Purpose Returns the AMI method object associated with this invocation or subscription.
Remarks Use the instance.of operator to determine whether this AMI method is an AmiAsyncMethodInterface.
Returns The AMI method interface object.
TIBCO Hawk AMI Java Reference AmiMethodContext.getDuration() | 73
AmiMethodContext.getDuration() Method
Declaration public java.lang.Integer getDuration()
Purpose Returns the DURATION parameter of the asynchronous method subscription.
Remarks This method is only applicable to an asynchronous AMI method.
TIBCO Hawk AMI Java Reference 74 | Chapter 5 AMI Classes
AmiMethodContext.getArguments() Method
Declaration public AmiParameterList getArguments()
Purpose Returns the input arguments of the method invocation or subscription.
TIBCO Hawk AMI Java Reference AmiMethodContext.getReplySubject() | 75
AmiMethodContext.getReplySubject() Method
Declaration public java.lang.String getReplySubject()
Purpose Returns the reply subject of the method invoker or subscriber.
Remarks Please note that this subject and the context number represents an unique method invocation or subscription.
See Also AmiMethodContext.getContext(), page 76 AmiMethodContext.equals(), page 77
TIBCO Hawk AMI Java Reference 76 | Chapter 5 AMI Classes
AmiMethodContext.getContext() Method
Declaration public java.lang.Integer getContext()
Purpose Returns this method invocation/subscription context number.
Remarks Please note that this subject and the context number represents an unique method invocation or subscription.
See Also AmiMethodContext.getReplySubject(), page 75 AmiMethodContext.equals(), page 77
TIBCO Hawk AMI Java Reference AmiMethodContext.equals() | 77
AmiMethodContext.equals() Method
Declaration public boolean equals(AmiMethodContext context)
Purpose Tests whether the specified AmiMethodContext is equivalent of this object. Returns true if the context is equivalent of this object. False otherwise.
Remarks To determine whether the specified context is equivalent to this object, the reply subject and context number are compared to see if they have the same value.
Parameters Parameter Description context The context with which to compare this object.
See Also AmiMethodContext.getReplySubject(), page 75 AmiMethodContext.getContext(), page 76
TIBCO Hawk AMI Java Reference 78 | Chapter 5 AMI Classes
AmiMethodContext.hashCode() Method
Declaration public int hashCode()
Purpose Returns a hash code value for the object.
Remarks This method is supported for the benefit of hash tables, such as those provided by java.util.Hashtable.
Returns The object’s hash code.
Overrides hashCode() in class java.lang.Object
TIBCO Hawk AMI Java Reference AmiMethodType | 79
AmiMethodType Class COM.TIBCO.hawk.ami.AmiMethodType
Declaration public class AmiMethodType extends java.lang.Object
Purpose The AmiMethodType class serves to indicate the kind of AMI methods that can be instrumented. This class does not provide a public constructor. Instead, three static object of this class are available in the AmiConstants class: • AmiConstants.METHOD_TYPE_INFO
• AmiConstants.METHOD_TYPE_ACTION
• AmiConstants.METHOD_TYPE_ACTION_INFO
Method Method Description Page Summary AmiMethodType.toString() Returns the string representation of the 80 AMI method type object.
AmiMethodType.fromString() Returns the type object according to the 81 input type string.
AmiMethodType.equals() Determines whether the specified 82 method type is equivalent with this object.
AmiMethodType.hashCode() Returns a hash code value for the 83 object.
See Also AmiMethod, page 43 AmiAsyncMethod, page 59 AmiErrors, page 42 AmiErrors, page 42 AmiConstants, page 41
TIBCO Hawk AMI Java Reference 80 | Chapter 5 AMI Classes
AmiMethodType.toString() Method
Declaration public java.lang.String toString()
Purpose Returns the string representation of the AMI method type object.
Returns The string representation of this object. Possible return strings are: • INFO:Method that returns information only. • ACTION:Method that performs an action. • ACTION_INFO:Method that performs both an action and returns information.
Overrides toString in class java.lang.Object
See Also AmiErrors, page 42
AmiConstants, page 41
TIBCO Hawk AMI Java Reference AmiMethodType.fromString() | 81
AmiMethodType.fromString() Method
Declaration public static AmiMethodType fromString(java.lang.String typeString)
Purpose Returns the type object according to the input type string.
Remarks If null is specified as the typeString, then AmiConstants.METHOD_TYPE_INFO object is returned.
Parameters Parameter Description typeString String form of the AMI method type.
TIBCO Hawk AMI Java Reference 82 | Chapter 5 AMI Classes
AmiMethodType.equals() Method
Declaration public boolean equals(AmiMethodType type)
Purpose Determines whether the specified method type is equivalent with this object.
Returns True if the two objects are equivalent. False otherwise.
TIBCO Hawk AMI Java Reference AmiMethodType.hashCode() | 83
AmiMethodType.hashCode() Method
Declaration public int hashCode()
Purpose Returns a hash code value for the object.
Remarks This method is supported for the benefit of hash tables such as those provided by java.util.Hashtable.
Returns The object’s hash code.
Overrides hashCode() in class java.lang.Object
TIBCO Hawk AMI Java Reference 84 | Chapter 5 AMI Classes
ComponentVersion Class COM.TIBCO.hawk.ami.ComponentVersion
Declaration public class ComponentVersion extends java.lang.Object implements COM.TIBCO.hawk.util.release.Component
Purpose Version identification class for a specific component.
Remarks An instance of the ComponentVersion class is used in conjunction with an instance of the AmiGetVersionMethod class. The AmiGetVersionMethod class adds the getReleaseVersion() method to your AMI interface. The getReleaseVersion() method returns a table of version information with one row for each ComponentVersion instance that was added to the AmiGetVersionMethod instance.
Typically, an AMI application adds a single ComponentVersion representing the AMI application. However, if the AMI application consists of several components with individual version, then multiple ComponentVersions can be added.
See Also AmiGetVersionMethod, page 65
Member Member Description Page Summary ComponentVersion.Co Constructor 85 mponentVersion()
ComponentVersion.get Returns the table describing this component's 86 ComponentInfo() version information.
TIBCO Hawk AMI Java Reference ComponentVersion.ComponentVersion() | 85
ComponentVersion.ComponentVersion() Constructor
Declaration public ComponentVersion()
public ComponentVersion( java.lang.String inName, java.lang.String inVersion, int inMajorVersion, int inMinorVersion, int inUpdateVersion, java.lang.String inDate)
Purpose Provides version identification class for the AMI Java API.
Remarks By specifying parameters, users can create ComponentVersion objects for their AMI applications. All instances of this class returns the same table of version information.
Parameters Parameter Description inName Component name.
inVersion Component version.
inMajorVersion Component major version.
inMinorVersion Component minor version.
inUpdateVersion Component patch version.
inDate Component build date.
TIBCO Hawk AMI Java Reference 86 | Chapter 5 AMI Classes
ComponentVersion.getComponentInfo() Method
Declaration public java.util.Hashtable getComponentInfo()
Purpose Returns the table describing this component's version information.
Returns The table containing the version information for this package.
TIBCO Hawk AMI Java Reference | 87
Chapter 6 AMI Parameters
The class AmiParameter describes a parameter used either as an argument or return value. An AmiParameter describes the attributes of an input or output parameter of an AmiMethodInterface. Its methods are given later in this section.
AmiParameterList is passed as a parameter to AmiMethod, AmiMethodAsync and AmiMethodRepeating.
Topics
• AmiParameter, page 88 • AmiParameterList, page 99
TIBCO Hawk AMI Java Reference 88 | Chapter 6 AMI Parameters
AmiParameter Abstract class COM.TIBCO.hawk.ami.AmiParameter
Declaration public class AmiParameter extends java.lang.Object
Purpose An AmiParameter describes the attributes of an input or output parameter of an AmiMethodInterface.
An AmiParameter name must be a non-null string. The supported Java primitive types are boolean, byte, sort, int, long, float and double. The supported Java classes are String, Boolean, and Number class. Only minimal argument checking is performed in the constructors and other methods of this class. More rigorous validation checks are performed during AmiSession.addMethod(AmiMethodInterface) if, and only if, the AmiSession's trace level has the AMI_AMI bit turned on.
See Also AmiSession.addMethod(), page 19 AmiTraceInterface, page 122
Method Method Description Page Summary AmiParameter.AmiParameter() Constructor 90
Accessor Methods
AmiParameter.getHelp() Returns the help text of the 95 parameter.
AmiParameter.getLegalChoices() Returns an array of legal choices 93 object associated with this AmiParameter.
AmiParameter.getName() Returns the name of this 92 AmiParameter object.
AmiParameter.getValue() Returns the sample value object for 95 this AmiParameter object.
AmiParameter.getValueChoices() Returns an array of value choices 98 object associated with this AmiParameter
TIBCO Hawk AMI Java Reference AmiParameter | 89
Method Description Page Set Methods
AmiParameter.setLegalChoices() Sets the legal choices for this AMI 97 parameter with an array of the specified type. Array types are: objects, byte, short, int, long, float, and double.
AmiParameter.setValueChoices() Sets the value choices for this AMI 98 parameter with an array of the specified type. Array types are: objects, byte, short, int, long, float, and double.
TIBCO Hawk AMI Java Reference 90 | Chapter 6 AMI Parameters
AmiParameter.AmiParameter() Constructor
Declaration public AmiParameter( java.lang.String name, java.lang.String help, java.lang.Object value)
public AmiParameter( java.lang.String name, java.lang.String help, boolean value)
public AmiParameter( java.lang.String name, java.lang.String help, byte value)
public AmiParameter( java.lang.String name, java.lang.String help, short value)
public AmiParameter( java.lang.String name, java.lang.String help, int value)
public AmiParameter( java.lang.String name, java.lang.String help, long value)
public AmiParameter( java.lang.String name, java.lang.String help, float value)
public AmiParameter( java.lang.String name, java.lang.String help, double value)
public AmiParameter( java.lang.String name, java.lang.Object value)
public AmiParameter( java.lang.String name, boolean value)
public AmiParameter( java.lang.String name, byte value)
TIBCO Hawk AMI Java Reference AmiParameter.AmiParameter() | 91
public AmiParameter( java.lang.String name, short value)
public AmiParameter( java.lang.String name, int value)
public AmiParameter( java.lang.String name, long value)
public AmiParameter( java.lang.String name, float value)
public AmiParameter( java.lang.String name, double value)
Purpose Constructor to create an instance of AmiParameter object. The different forms allow you to use different types.
Remarks For boolean parameter type, the legal choices are true or false.
Parameters Name Description
name Name of the parameter. Note: The use of curly brackets { } in microagent method parameter names is not supported. Use of these characters results in an error.
help Help text of the parameter.
value Value of the parameter. The supported Java classes for this parameter are String, Boolean or Number classes (including BigInteger). The supported data types are boolean, short, long, byte, int, float, and double.
TIBCO Hawk AMI Java Reference 92 | Chapter 6 AMI Parameters
AmiParameter.getHelp() Method
Declaration public java.lang.String getHelp()
Purpose Returns the help text of the parameter.
Returns The help text of the AMI parameter object.
TIBCO Hawk AMI Java Reference AmiParameter.getLegalChoices() | 93
AmiParameter.getLegalChoices() Method
Declaration public java.lang.Object[] getLegalChoices()
Purpose Returns an array of legal choices object associated with this AmiParameter.
Returns An array of the legal choice objects.
TIBCO Hawk AMI Java Reference 94 | Chapter 6 AMI Parameters
AmiParameter.getName() Method
Declaration public java.lang.String getName()
Purpose Returns the name of this AmiParameter object.
TIBCO Hawk AMI Java Reference AmiParameter.getValue() | 95
AmiParameter.getValue() Method
Declaration public java.lang.Object getValue()
Purpose Returns the sample value object for this AmiParameter object.
TIBCO Hawk AMI Java Reference 96 | Chapter 6 AMI Parameters
AmiParameter.getValueChoices() Method
Declaration public java.lang.Object[] getValueChoices()
Purpose Returns an array of the value choices objects associated with this AmiParameter.
TIBCO Hawk AMI Java Reference AmiParameter.setLegalChoices() | 97
AmiParameter.setLegalChoices() Method
Declaration public void setLegalChoices(java.lang.Object[] choices) public void setLegalChoices(byte[] choices) public void setLegalChoices(short[] choices) public void setLegalChoices(int[] choices) public void setLegalChoices(long[] choices) public void setLegalChoices(float[] choices) public void setLegalChoices(double[] choices)
Purpose Sets the legal choices for this AmiParameter with an array of objects or an array of the specified type (byte, short, int, long, float, or double).
Remarks The supported Java classes for this parameter are arrays of String, Boolean or Number classes. No error checking is performed in this method.
Parameters Parameter Description choices Array of choices.
TIBCO Hawk AMI Java Reference 98 | Chapter 6 AMI Parameters
AmiParameter.setValueChoices() Method
Declaration public void setValueChoices(java.lang.Object[] choices) public void setValueChoices(byte[] choices) public void setValueChoices(short[] choices) public void setValueChoices(int[] choices) public void setValueChoices(long[] choices) public void setValueChoices(float[] choices) public void setValueChoices(double[] choices)
Purpose Sets the value choices for this AmiParameter with an array of objects or an array of the specified type (byte, short, int, long, float, or double).
Parameters Parameter Description choices Array of choices.
TIBCO Hawk AMI Java Reference AmiParameterList | 99
AmiParameterList Class java.util.AbstractCollection java.util.AbstractList java.util.Vector COM.TIBCO.hawk.ami.AmiParameterList
Declaration public class AmiParameterList extends java.util.Vector
Purpose Instances of AmiParameterList store a collection AmiParameter objects.
Method Method Description Page Summary AmiParameterList.AmiParameterList() Constructor 100
TIBCO Hawk AMI Java Reference 100 | Chapter 6 AMI Parameters
AmiParameterList.AmiParameterList() Constructor
Declaration public AmiParameterList()
public AmiParameterList(int size)
Purpose Creates an instance of AmiParameterList.
Parameters Parameter Description
size Set the initialize size of the list.
TIBCO Hawk AMI Java Reference | 101
Chapter 7 AMI Interfaces
The AmiInterface parameters interact with the AMI methods to allows a Java class to implement a getMethods method, support communication, and allow error tracing.
Topics
• AmiEnabledInterface, page 102 • AmiMethodInterface, page 106 • AmiAsyncMethodInterface, page 119 • AmiTraceInterface, page 122
TIBCO Hawk AMI Java Reference 102 | Chapter 7 AMI Interfaces
AmiEnabledInterface Interface AmiEnabledInterface AmiMethodInterface AmiAsyncMethodInterface AmiTraceInterface
Declaration public abstract interface AmiEnabledInterface
All Known Implementing Classes
AmiSession, AmiTrace
Purpose The AmiEnabledInterface interface allows any class to implement a getMethods() method that returns an array of AmiMethodInterface objects. This feature enables a class object to AMI-instrument itself through the AmiSession.addMethod() method.
For example, the AmiTrace object implements the AmiEnabledInterface and its method getMethods() returns an array of AmiMethodInterface objects related to get and set of AmiTrace properties. An example use of the AmiTrace object in conjunction with AmiSession would be: string amiName = "COM.TIBCO.ami.test1"; string amiDisplayName = "test1"; string amiHelp = "An AMI Java test"; TibrvTransport rvTransport = new TirvRvdTransport ("7474", null, "tcp:7474"); TirvQueue rvQueue = new TibrvQueue(); AmiTrace trace = null; AmiSession ami = null;
// Initialize a trace object trace = new AmiTrace(); trace.setLevel(trace.AMI_INFO | trace.AMI_WARNING);
// Initialize an AMI session object ami = new AmiSession(rvTransport, rvQueue, amiName, amiDisplayName, amiHelp, trace);
// Perform other operations ...
// Enable the AmiMethodInterfaces implemented by the trace object ami.addMethods(trace);
...
TIBCO Hawk AMI Java Reference AmiEnabledInterface | 103
Method Method Description Page Summary AmiEnabledInterface.getMethods() Returns an array of 104 AmiMethodInterface.
AmiEnabledInterface.setSession() Sets the AmiSession object for the 105 class implementing this interface
See Also AmiMethodInterface, page 106 AmiSession.addMethod(), page 19 AmiTrace, page 194 AmiTrace.setSession(), page 204
TIBCO Hawk AMI Java Reference 104 | Chapter 7 AMI Interfaces
AmiEnabledInterface.getMethods() Method
Declaration public AmiMethodInterface[] getMethods() throws AmiException
Purpose Returns an array of AmiMethodInterface instances
Returns AmiMethodInterface[] When an instance object of a class that implements this interface is added to the AmiSession through addMethods, getMethods is invoked
See Also AmiSession.addMethods(), page 20:
TIBCO Hawk AMI Java Reference AmiEnabledInterface.setSession() | 105
AmiEnabledInterface.setSession() Method
Declaration public void setSession(AmiSession ami) throws AmiException
Purpose Sets the AmiSession object for the class implementing this interface.
Remarks This method is invoked by AmiSession.addMethods before it invokes the getMethods method. This is in case the implementing class needs the current AmiSession object.
Parameters Parameter Description
ami The current AmiSession object.
TIBCO Hawk AMI Java Reference 106 | Chapter 7 AMI Interfaces
AmiMethodInterface Interface AmiParameter AmiMethodInterface AmiAsyncMethodInterface AmiAsyncMethodInterface
Declaration public abstract interface AmiMethodInterface
All Known Sub-Interfaces:
AmiAsyncMethodInterface
All Known Implementing Classes:
AmiGetVersionMethod, AmiMethod
Purpose AmiMethodInterface interface describes an AMI synchronous method. An AMI synchronous method supports the request/reply communication paradigm. An application that implements the synchronous method becomes the server and the monitoring TIBCO Hawk agent becomes its client. When the monitoring agent sends a method invocation, this invocation is the request. The AMI Java API converts this invocation request into a call to the application’s onInvoke method. When onInvoke() returns, its result is converted into a reply message and sent back to the original agent that made the request.
Method Method Description Page Summary AmiMethodInterface.getArguments() Returns the parameter list that 108 describes the input parameters of this AMI method.
AmiMethodInterface.getHelp() Returns the help text that 109 describes the functionality of this AMI method.
AmiMethodInterface.getIndexName() Returns the index parameter 110 name of this method.
AmiMethodInterface.getName() Returns the name of this AMI 111 method.
TIBCO Hawk AMI Java Reference AmiMethodInterface | 107
Method (Cont’d) Description (Cont’d) Page AmiMethodInterface.getReturns() Returns the parameter list that 112 describes the output parameters of this AMI method.
AmiMethodInterface.getSession() Returns the AMI session that 113 owns this AMI method.
AmiMethodInterface.getTimeout() Returns the timeout period for 114 this AMI method.
AmiMethodInterface.getType() Returns the type of this AMI 116 method.
AmiMethodInterface.onInvoke() Implements the method actions 116 when this AMI method is invoked by the TIBCO Hawk agent.
AmiMethodInterface.setIndexName() Sets the AMI method's index 117 parameter name.
AmiMethodInterface.setSession() Sets the AMI session object 118 with which to associate this method.
TIBCO Hawk AMI Java Reference 108 | Chapter 7 AMI Interfaces
AmiMethodInterface.getArguments() Method
Declaration public AmiParameterList getArguments()
Purpose Returns the parameter list that describes the input parameters of this AMI method.
Returns An AmiParameterList object containing the input parameters of this AMI method.
A NULL value is returned, if this method does not accept any parameters.
TIBCO Hawk AMI Java Reference AmiMethodInterface.getHelp() | 109
AmiMethodInterface.getHelp() Method
Declaration public java.lang.String getHelp()
Purpose Returns the help text that describes the functionality of this AMI method.
Returns The help text describing the functionality of this AMI method.
TIBCO Hawk AMI Java Reference 110 | Chapter 7 AMI Interfaces
AmiMethodInterface.getIndexName() Method
Declaration public java.lang.String [] getIndexName()
Purpose Returns the index parameter name of this method.
Remarks When a method returns multiple rows of data, an index parameter name should be indicated. This method should return null if this AMI method does not return multiple rows of data.
Returns The index parameter names of this method.
TIBCO Hawk AMI Java Reference AmiMethodInterface.getName() | 111
AmiMethodInterface.getName() Method
Declaration public java.lang.String getName()
Purpose Returns the name of this AMI method as a string.
TIBCO Hawk AMI Java Reference 112 | Chapter 7 AMI Interfaces
AmiMethodInterface.getReturns() Method
Declaration public AmiParameterList getReturns()
Purpose Returns the parameter list that describes the output parameters of this AMI method.
Remarks AMI methods of the type AmiConstants.METHOD_TYPE_INFO and AmiConstants.METHOD_TYPE_ACTION_INFO are required to return a non-null and non-empty list of the output parameter list.
Returns An AmiParameterList object containing the output parameters of this AMI method.
A NULL value should be returned, if this method does not return any output parameters. This is usually the case if this AMI method is an ACTION method.
AMI methods of type INFO and ACTION_INFO are required to return a non-null and non-empty list of output parameter list.
TIBCO Hawk AMI Java Reference AmiMethodInterface.getSession() | 113
AmiMethodInterface.getSession() Method
Declaration public AmiSession getSession()
Purpose Returns the AMI session that owns this AMI method.
Returns The AMI session that owns this AMI method.
TIBCO Hawk AMI Java Reference 114 | Chapter 7 AMI Interfaces
AmiMethodInterface.getTimeout() Method
Declaration public int getTimeout()
Purpose Returns the timeout period for this AMI method.
Remarks If there is a possibility that this method would take a long time to return results, you would want to set and return a timeout value that reflects the worst-case scenario.
Returns The timeout value of this method, in milliseconds.
TIBCO Hawk AMI Java Reference AmiMethodInterface.getType() | 115
AmiMethodInterface.getType() Method
Declaration public AmiMethodType getType()
Purpose Returns the type of this AMI method.
Returns The type of this method. Possible return values can only be one of the following static objects: • AmiConstants.METHOD_TYPE_INFO • AmiConstants.METHOD_TYPE_ACTION • AmiConstants.METHOD_TYPE_ACTION_INFO
See Also AmiConstants, page 41
TIBCO Hawk AMI Java Reference 116 | Chapter 7 AMI Interfaces
AmiMethodInterface.onInvoke() Method
Declaration public AmiParameterList onInvoke(AmiParameterList args) throws java.lang.Exception
Purpose The onInvoke method implements the method actions when this AMI method is invoked by agent.
Remarks A Java.lang.Exception is thrown from this method is captured by the AMI Java API and is turned into an error reply. This error reply is sent back to the invoking agent as the result of the method invocation.
Parameters Parameter Description args List of arguments of same type as defined in getArguments(), except that each parameter in the list contains the corresponding input values.
Returns An AmiParameterList object as the result of this AmiMethodInterface invocation.
Throws The application can throw any Exception object from this method when the text message of the exception is used by the AMI API as the method invocation reply.
TIBCO Hawk AMI Java Reference AmiMethodInterface.setIndexName() | 117
AmiMethodInterface.setIndexName() Method
Declaration public void setIndexName(java.lang.String indexName)
public void setIndexName(java.lang.String [] indexName)
Purpose Sets the AMI method's index parameter name.
Remarks If you want to create a composite index, using multiple index entries, use the second constructor listed above.
Parameters Parameter Description indexName Name of the parameter(s) that serves as the index.
TIBCO Hawk AMI Java Reference 118 | Chapter 7 AMI Interfaces
AmiMethodInterface.setSession() Method
Declaration public void setSession(AmiSession ami) throws AmiException
Purpose Sets the AMI session object to which this method is to be associated.
Remarks An AMI method can only be associated with one AMI session. An exception is thrown if the user attempts to associate an AMI method to an AMI session for a second time.
Parameters Parameter Function ami The AMI session object to which this method is to be associated.
TIBCO Hawk AMI Java Reference AmiAsyncMethodInterface | 119
AmiAsyncMethodInterface Interface
Interface Hierarchy AmiParameter AmiMethodInterface AmiAsyncMethodInterface AmiTraceInterface
Declaration public abstract interface AmiAsyncMethodInterface extends AmiMethodInterface
All Known Implementing Classes:
AmiAsyncMethod
Purpose AmiAsyncMethodInterface interface describes an AMI asynchronous method.
Remarks The AmiAsyncMethodInterface complements the AmiMethodInterface, in that the asynchronous method provides or publishes (as opposed to using an invocation request/reply) for data that become available in a non-predetermined manner. Because of this, the AMI asynchronous method can be considered a publishing source.
See Also AmiMethodInterface, page 106
Method Method Description Page Summary AmiAsyncMethodInterface.onS This method is invoked by the AMI Java 120 tart() API when an interest, or subscription, on this asynchronous method arrives.
AmiAsyncMethodInterface.onS This method is invoked by the AMI Java 121 top() API when the interest on this asynchronous method no longer exists.
Methods inherited from interface COM.TIBCO.hawk.ami.AmiMethodInterface
getArguments, getHelp, getIndexName, getName, getReturns, getSession, getType, onInvoke, setIndexName, setSession
TIBCO Hawk AMI Java Reference 120 | Chapter 7 AMI Interfaces
AmiAsyncMethodInterface.onStart() Method
Declaration public void onStart( AmiMethodContext context, AmiParameterList args) throws java.lang.Exception
Purpose This method is invoked by the AMI Java API when an interest, or subscription, on this asynchronous method arrives.
Parameters Parameter Description
context The context associated with the subscription.
args The start subscription input arguments.
TIBCO Hawk AMI Java Reference AmiAsyncMethodInterface.onStop() | 121
AmiAsyncMethodInterface.onStop() Method
Declaration public void onStop( AmiMethodContext context, AmiParameterList args) throws java.lang.Exception
Purpose This method is invoked by the AMI Java API when the interest on this asynchronous method no longer exists.
Parameters Parameter Description
context The context associated with the subscription.
args The stop subscription input arguments.
TIBCO Hawk AMI Java Reference 122 | Chapter 7 AMI Interfaces
AmiTraceInterface Interface AmiParameter AmiMethodInterface AmiAsyncMethodInterface AmiTraceInterface
Declaration public abstract interface AmiTraceInterface
All Known Implementing Classes:
AmiTrace
Purpose The debug/error handler interface provides methods for dealing with AMI debug information and errors.
Trace Code Fields public static final int AMI_ALL public static final int AMI_ALWAYS public static final int AMI_INFO public static final int AMI_WARNING public static final int AMI_ERROR public static final int AMI_DEBUG public static final int AMI_AMI
Type Description AMI_ALL Trace level code for turning all trace levels.
AMI_ALWAYS Trace level code for always logging a specified message. This is a constant integer value for indicating that text message coded with this value is always logged to the trace file, no matter what the value of current trace level.
AMI_AMI Trace level code for logging AMI API debugging level message. This trace level is reserved for AMI API use only. If the current trace level is set with the bit AMI_DEBUG on, the constant integer value for indicating the text message coded with this value is logged to the trace file.
AMI_DEBUG Trace level code for logging generic debugging level message. If the current trace level is set with the bit AMI_DEBUG on, the constant integer value for indicating the text message coded with this value is logged to the trace file.
TIBCO Hawk AMI Java Reference AmiTraceInterface | 123
Type (Cont’d) Description (Cont’d) AMI_ERROR Trace level code for logging error level message. If the current trace level is set with the bit AMI_ERROR on, the constant integer value for indicating the text message coded with this value is logged to the trace file.
AMI_INFO Trace level code for logging information level message. If the current trace level is set with the bit AMI_INFO on, the constant integer value for indicating the text message coded with this value is logged to the trace file.
AMI_MIN_LEVEL The minimum allowable integer values for trace level.
AMI_WARNING Trace level code for logging warning level message. If the current trace level is set with the bit AMI_WARNING on, the constant integer value for indicating the text message coded with this value is logged to the trace file.
Method Method Description Page Summary Accessor Methods
AmiTraceInterface.getDirectoryName() Returns the current trace 126 directory path.
AmiTraceInterface.getFileName() Returns the current trace file 127 name.
AmiTraceInterface.getFileSize() Returns the current trace 128 maximum file size.
AmiTraceInterface.getLevel() Returns the current trace 129 level.
AmiTraceInterface.getLevelHelpString() Returns the help text 130 corresponding to the specified trace level.
AmiTraceInterface.getLevelLabelString() Returns the label string 131 corresponding to the specified trace level.
AmiTraceInterface.getLevelString() Returns the specified trace 132 level's string name.
AmiTraceInterface.getMaxFile() Returns the current trace 133 maximum number of files before purging occurs.
TIBCO Hawk AMI Java Reference 124 | Chapter 7 AMI Interfaces
Method (Cont’d) Description (Cont’d) Page AmiTraceInterface.getMaxLevel() Returns the current 134 maximum settable level.
AmiTraceInterface.getNumberOfLevels() Returns the current number 135 of distinct trace levels.
AmiTraceInterface.isLevelOn() Returns true if the give bit 136 set of the AMI API is turned on
Logging Methods
AmiTraceInterface.log() Logs the specified 137 parameters.
AmiTraceInterface.logAlways() Logs the specified 138 parameter with the AMI_ALWAYS bit.
AmiTraceInterface.logAmi() Logs the specified 139 parameter with the AMI_AMI bit.
AmiTraceInterface.logDebug() Logs the specified 140 parameter with the AMI_DEBUG bit.
AmiTraceInterface.logError() Logs the specified 141 parameter with the AMI_ERROR bit.
AmiTraceInterface.logInfo() Logs the specified 142 parameter with the AMI_INFO bit.
AmiTraceInterface.logWarning() Logs the specified message 143 with the AMI_WARNING bit.
Set Methods
AmiTraceInterface.setDirectoryName() Sets the trace directory path. 144
AmiTraceInterface.setFileName() Sets the current trace file 145 name.
TIBCO Hawk AMI Java Reference AmiTraceInterface | 125
Method (Cont’d) Description (Cont’d) Page AmiTraceInterface.setFileSize() Sets the current trace file 146 maximum size before rollover.
AmiTraceInterface.setLevel() Sets the current trace level 147 with the specified integer value.
AmiTraceInterface.setMaxFile() Sets the current trace 148 maximum number of log file before purging.
AmiTraceInterface.setUserLevel() Sets the next available user 149 definable trace level.
TIBCO Hawk AMI Java Reference 126 | Chapter 7 AMI Interfaces
AmiTraceInterface.getDirectoryName() Method
Declaration public java.lang.String getDirectoryName()
Purpose Returns the current trace directory path.
Returns The current directory path name.
TIBCO Hawk AMI Java Reference AmiTraceInterface.getFileName() | 127
AmiTraceInterface.getFileName() Method
Declaration public java.lang.String getFileName()
Purpose Returns the current trace file name.
Returns The current trace file name.
TIBCO Hawk AMI Java Reference 128 | Chapter 7 AMI Interfaces
AmiTraceInterface.getFileSize() Method
Declaration public long getFileSize()
Purpose Returns the current trace maximum file size.
Returns The current file size in Kilobytes.
TIBCO Hawk AMI Java Reference AmiTraceInterface.getLevel() | 129
AmiTraceInterface.getLevel() Method
Declaration public int getLevel()
Purpose Returns the current trace level.
Returns The current trace level.
TIBCO Hawk AMI Java Reference 130 | Chapter 7 AMI Interfaces
AmiTraceInterface.getLevelHelpString() Method
Declaration public java.lang.String getLevelHelpString(int code)
Purpose Returns the help text corresponding to the specified trace level.
Parameters Parameter Description code Trace level to query for help text.
TIBCO Hawk AMI Java Reference AmiTraceInterface.getLevelLabelString() | 131
AmiTraceInterface.getLevelLabelString() Method
Declaration public java.lang.String getLevelLabelString(int code)
Purpose Returns the label string corresponding to the specified trace level.
Parameters Parameter Description code Trace level to query for label string.
TIBCO Hawk AMI Java Reference 132 | Chapter 7 AMI Interfaces
AmiTraceInterface.getLevelString() Method
Declaration public java.lang.String getLevelString(int level)
Purpose Returns the specified trace level's string name.
Parameters Parameter Description
level The trace level for whose description is requested.
Returns The text corresponding to the specified trace level.
TIBCO Hawk AMI Java Reference AmiTraceInterface.getMaxFile() | 133
AmiTraceInterface.getMaxFile() Method
Declaration public long getMaxFile()
Purpose Returns the current trace maximum number of files before purging occurs.
TIBCO Hawk AMI Java Reference 134 | Chapter 7 AMI Interfaces
AmiTraceInterface.getMaxLevel() Method
Declaration public int getMaxLevel()
Purpose Returns the current maximum settable level.
TIBCO Hawk AMI Java Reference AmiTraceInterface.getNumberOfLevels() | 135
AmiTraceInterface.getNumberOfLevels() Method
Declaration public int getNumberOfLevels()
Purpose Returns the current number of distinct trace levels.
TIBCO Hawk AMI Java Reference 136 | Chapter 7 AMI Interfaces
AmiTraceInterface.isLevelOn() Method
Declaration public boolean isLevelOn(int code)
Purpose Returns true if the specified bit set of the AMI API is turned on.
Parameters Parameter Description code The bit set whose value is requested.
Returns The implementation for this method should return true if the specified bit set is set in the current trace object.
TIBCO Hawk AMI Java Reference AmiTraceInterface.log() | 137
AmiTraceInterface.log() Method
Declaration public void log( int code, java.lang.String msg)
public void log( int code, java.lang.Exception e)
public void log( int code, java.lang.String msg, java.lang.Exception e)
Purpose Logs a message if the current trace level has the specified code set. • The first form logs a message if the current trace level has the specified code set. The only exception is if the specified code is AMI_ALWAYS and AMI_ERROR; in this case, the message is logged to the trace file, regardless of the current trace level.
• The second form logs the specified Exception's stack trace.
• The third form logs the specified Exception's stack trace.
Remarks Logs the message if the current trace level contains the specified code set. The only exception is if the specified code is AMI_ALWAYS and AMI_ERROR; in this case, the message is logged to the trace file, regardless of the current trace level.
Parameters Parameter Description
code A trace level code.
msg The message to log.
e The exception object to log.
TIBCO Hawk AMI Java Reference 138 | Chapter 7 AMI Interfaces
AmiTraceInterface.logAlways() Method
Declaration public void logAlways(java.lang.String msg)
public void logAlways(java.lang.Exception e)
Purpose Logs the specified parameter with the AMI_ALWAYS bit.
• The first form is equivalent to invoking the method log(Trace.AMI_ALWAYS, msg). • The second form is equivalent to invoking the method log(Trace.AMI_ALWAYS, e).
Parameters Parameter Description
msg The message to log.
e The exception object to log.
TIBCO Hawk AMI Java Reference AmiTraceInterface.logAmi() | 139
AmiTraceInterface.logAmi() Method
Declaration public void logAmi(java.lang.String msg)
public void logAmi(java.lang.Exception e)
Purpose Logs the specified parameter with the AMI_AMI bit.
• The first form is equivalent to invoking the method log(Trace.AMI_AMI, msg).
• The second form is equivalent to invoking the method log(Trace.AMI_AMI, e).
Parameters Parameter Description msg The message to log.
e The exception object to log.
TIBCO Hawk AMI Java Reference 140 | Chapter 7 AMI Interfaces
AmiTraceInterface.logDebug() Method
Declaration public void logDebug(java.lang.String msg)
public void logDebug(java.lang.Exception e)
Purpose Logs the specified parameter with the AMI_DEBUG bit.
• The first form is equivalent to invoking the method log(Trace.AMI_DEBUG, msg). • The second form is equivalent to invoking the method log(Trace.AMI_DEBUG, e).
Parameters Parameter Description msg The message to log.
e The exception object to log.
TIBCO Hawk AMI Java Reference AmiTraceInterface.logError() | 141
AmiTraceInterface.logError() Method
Declaration public void logError(java.lang.String msg)
public void logError(java.lang.Exception e)
Purpose Logs the specified parameter with the AMI_ERROR bit.
• The first form is equivalent to invoking the method log(Trace.AMI_ERROR, msg). • The second form is equivalent to invoking the method log(Trace.AMI_ERROR, e).
Parameters Parameter Description
msg The message to log.
e The exception object to log.
TIBCO Hawk AMI Java Reference 142 | Chapter 7 AMI Interfaces
AmiTraceInterface.logInfo() Method
Declaration public void logInfo(java.lang.String msg)
public void logInfo(java.lang.Exception e)
Purpose Logs the specified parameter with the AMI_INFO bit.
• The first form is equivalent to invoking the method log(Trace.AMI_INFO, msg).
• The second form is equivalent to invoking the method log(Trace.AMI_INFO, e).
Parameters Parameter Description
msg The message to log.
e The exception object to log.
TIBCO Hawk AMI Java Reference AmiTraceInterface.logWarning() | 143
AmiTraceInterface.logWarning() Method
Declaration public void logWarning(java.lang.String msg)
public void logWarning(java.lang.Exception e)
Purpose Logs the specified parameter with the AMI_WARNING bit. • The first form is equivalent to invoking the method log(Trace.AMI_WARNING, msg). • The second form is equivalent to invoking the method log(Trace.AMI_WARNING, e).
Parameters Parameter Description msg The message to log.
e The exception object to log.
TIBCO Hawk AMI Java Reference 144 | Chapter 7 AMI Interfaces
AmiTraceInterface.setDirectoryName() Method
Declaration public void setDirectoryName(java.lang.String dirName) throws HawkException
Purpose Sets the current trace directory path.
Parameters Parameter Description
dirName Directory path name.
TIBCO Hawk AMI Java Reference AmiTraceInterface.setFileName() | 145
AmiTraceInterface.setFileName() Method
Declaration public void setFileName(java.lang.String fileName) throws HawkException
Purpose Sets the current trace file name.
Parameters Parameter Description fileName Name of the log file.
TIBCO Hawk AMI Java Reference 146 | Chapter 7 AMI Interfaces
AmiTraceInterface.setFileSize() Method
Declaration public void setFileSize(long fileSize) throws HawkException
Purpose Sets the current trace file maximum size before rollover.
Parameters Parameter Description fileSize Size of the file in Kilobytes.
TIBCO Hawk AMI Java Reference AmiTraceInterface.setLevel() | 147
AmiTraceInterface.setLevel() Method
Declaration public void setLevel(int level) throws HawkException
Purpose Sets the current trace level with the specified integer value.
Remarks When the specified level is the value ALL, all trace levels are turned on. Any combinations of the trace levels can be turned on by | the levels together. For example: AmiTrace trace = new AmiTrace(); trace.setLevel(trace.AMI_INFO | trace.AMI_DEBUG);
Parameters Parameter Description
level Level value representation of the trace level.
Throws HawkException is thrown if the integer value is out of the legal range.
TIBCO Hawk AMI Java Reference 148 | Chapter 7 AMI Interfaces
AmiTraceInterface.setMaxFile() Method
Declaration public void setMaxFile(long maxFile) throws HawkException
Purpose Sets the current trace maximum number of log file before purging.
Parameters Parameter Description maxFile Maximum number of rolled over files to keep.
TIBCO Hawk AMI Java Reference AmiTraceInterface.setUserLevel() | 149
AmiTraceInterface.setUserLevel() Method
Declaration public int setUserLevel( java.lang.String user, java.lang.String label, java.lang.String help)
Purpose Sets the next available user-definable trace level.
Parameters Parameter Description
user User defined trace level string.
label User defined trace level label string.
help User defined trace level help text.
Returns The next available user trace level.
TIBCO Hawk AMI Java Reference 150 | Chapter 7 AMI Interfaces
TIBCO Hawk AMI Java Reference | 151
Chapter 8 AMI Exception Classes
The exception classes provide exception and error handling capabilities for the Java API.
Topics
• HawkException, page 152 • AmiException, page 159 • ResourceException, page 161 • TraceException, page 163
TIBCO Hawk AMI Java Reference 152 | Chapter 8 AMI Exception Classes
HawkException Class java.lang.Throwable java.lang.Exception COM.TIBCO.hawk.utilities.exception.HawkExceptions AmiException ResourceException TraceException
Direct Known Subclasses
AmiException, ResourceException, TraceException
Declaration public class HawkException extends java.lang.Exception
Description Each HawkException instance embeds an error code and an error message for retrieval by the methods getCode() and getMessage(), respectively. When the TIBCO Hawk software throws a HawkException, the error code and error message are stored internally.
Each TIBCO Hawk Java package that uses HawkException must extend from the HawkException class and register a unique range of error codes for its own use. The primary purpose of this mechanism is administration of a set of unique non-overlapping error codes between the various TIBCO Hawk Java packages. Provides both a framework for generating exceptions with unique error codes and also provides an exception class with finer error identification capability by use of unique error codes. The programmer can thus better differentiate and deal with the exception condition.
To register a TIBCO Hawk Java package's error code with HawkException:
1. Choose the HawkException subclass name corresponding to the TIBCO Hawk component. For example, for TIBCO Hawk AMI package, the exception class name would be COM.TIBCO.hawk.ami.AmiException. 2. Choose a unique range of unused error code. For example, for COM.TIBCO.hawk.ami.AmiException you might use the error code range of 5001 to 6000.
3. Register the class name and the error code range in HawkException by creating an new instance object of class MinMaxRange using the previously-chosen class name, error minimum and error maximum codes.
TIBCO Hawk AMI Java Reference HawkException | 153
This new instance object, of class MinMaxRange, is inserted into the m_minMax array. A code sample is shown below.
protected static MinMaxRange[] m_minMax= { new MinMaxRange( "COM.TIBCO.hawk.utilities.exception.HawkException", 1, 1000), new MinMaxRange( "COM.TIBCO.hawk.utilities.trace.TraceException", 1001, 2000), new MinMaxRange( "COM.TIBCO.hawk.utilities.trace.TraceException", 5001, 6000) }; // m_minMax
4. Implement the COM.TIBCO.hawk.ami.AmiException class as a subclass of HawkException.
5. From this point, when creating an instance of AmiException class, use the error code within its registered error code range.
Direct Known Subclasses
AmiException, ResourceException, TraceException
Method Method Description Page Summary HawkException.HawkException() Constructor 154
HawkException.getCode() Returns the error code of this 155 exception object.
HawkException.getMax() Returns the maximum error code 156 range for this exception object.
HawkException.getMessage() Returns the error message of this 157 exception object.
HawkException.getMin() Returns the minimum error code 158 range for this exception object.
Methods inherited from class java.lang.Throwable
fillInStackTrace, getLocalizedMessage, printStackTrace, printStackTrace, printStackTrace, toString
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, wait
TIBCO Hawk AMI Java Reference 154 | Chapter 8 AMI Exception Classes
HawkException.HawkException() Constructor
Description public HawkException( int code, java.lang.String message)
public HawkException(HawkException hawkException)
Purpose Constructor for creating a instances of HawkException class.
• The first form creates a HawkException from scratch.
• The second form converts an existing HawkException for the purpose of re-throwing it among subclass of HawkException.
Remarks It is acceptable for subclasses of HawkException to use HawkErrors codes when constructing instances of the subclass.
The constructor for converting an existing HawkException for the purpose of re-throwing it to subclass of HawkException allows any of the subclasses of HawkException to convert each other's exception objects, if different packages have interdependencies.
If the subclass of HawkException is not registered with HawkException, then the resulting exception object has HAWK_UNKNOWN_EXCEPTION_CLASS as the return value of its getCode() call.
The subclass of HawkException must use an error code within the range of its registration. If the input code value is out of its registered range, the resulting exception object has HAWK_ERROR_OUT_OF_RANGE as the return value of its getCode() call.
Parameters Parameter Description hawkException The exception to convert.
code The exception error code.
message The exception error message.
See Also HawkErrors, page 206
TIBCO Hawk AMI Java Reference HawkException.getCode() | 155
HawkException.getCode() Method
Declaration public int getCode()
Purpose Returns the error code of this exception object.
TIBCO Hawk AMI Java Reference 156 | Chapter 8 AMI Exception Classes
HawkException.getMax() Method
Declaration public final int getMax()
Purpose Returns the maximum error code range for this exception object.
TIBCO Hawk AMI Java Reference HawkException.getMessage() | 157
HawkException.getMessage() Method
Declaration public java.lang.String getMessage()
Purpose Returns the error message of this exception object.
Overrides getMessage in class java.lang.Throwable
TIBCO Hawk AMI Java Reference 158 | Chapter 8 AMI Exception Classes
HawkException.getMin() Method
Declaration public final int getMin()
Purpose Returns the minimum error code range for this exception object.
TIBCO Hawk AMI Java Reference AmiException | 159
AmiException Class java.lang.Throwable java.lang.Exception HawkException AmiException ResourceException TraceException
Declaration public class AmiException extends HawkException
Purpose The AmiException extends HawkException for use when an error condition occurs while executing a method invocation.
Methods inherited from class COM.TIBCO.hawk.utilities.exception.HawkException
getCode, getMax, getMessage, getMin
See Also HawkException, page 152
TIBCO Hawk AMI Java Reference 160 | Chapter 8 AMI Exception Classes
AmiException.AmiException() Constructor
Declaration public AmiException (int code, java.lang.String error)
public AmiException(HawkException hawkException)
Purpose Constructor to create an instance of AmiException. • The first form creates an instance using the specified code and error string.
• The second form converts a HawkException to AmiException for the purpose of re-throwing the exception.
Remarks The error code creating an instance of AmiException must be in the legal ranges of HawkErrors and AmiErrors. When propagating (re-throwing) an exception caught from other TIBCO Hawk packages, you must use the second form of the constructor.
Parameters Parameter Description code The error code indicating the exception condition.
error The error text corresponding to this exception condition.
hawkException The existing exception to be converted.
See Also AmiErrors, page 42 HawkErrors, page 206 HawkException, page 152 ResourceException, page 161
TIBCO Hawk AMI Java Reference ResourceException | 161
ResourceException Class java.lang.Throwable java.lang.Exception HawkException AmiException ResourceException TraceException
Declaration public class ResourceException extends HawkException
Purpose This class defines a resources package specific exception class. This class extends HawkException to return a standard TIBCO Hawk exception containing a unique exception code, as well as the standard exception string. The HawkException also allows this class to reserve a range of exception codes.
Methods inherited from class COM.TIBCO.hawk.utilities.exception.HawkException getCode, getMax, getMessage, getMin
See Also HawkException, page 152
TIBCO Hawk AMI Java Reference 162 | Chapter 8 AMI Exception Classes
ResourceException.ResourceException() Constructor
Declaration public ResourceException(int inCode, java.lang.String inDescription)
Purpose Constructs a ResourceException. ResourceException error codes must be within the range defined for the resources package in the HawkException base class.
Parameters Parameter Description
inCode The exception error code.
inDescription The exception description.
TIBCO Hawk AMI Java Reference TraceException | 163
TraceException Class java.lang.Throwable java.lang.Exception HawkException AmiException ResourceException TraceException
Declaration public class TraceException extends HawkException
Purpose The TraceException extends HawkException for use in cases where an error condition occurs while execting tracing methods.
Constructors public TraceException (int code, java.lang.String error)
public TraceException(HawkException hawkException)
Methods inherited from class COM.TIBCO.hawk.utilities.exception.HawkException
getCode, getMax, getMessage, getMin
See Also HawkException, page 152
TIBCO Hawk AMI Java Reference 164 | Chapter 8 AMI Exception Classes
TraceException.TraceException() Constructor
Declaration public TraceException (int code, java.lang.String error)
public TraceException(HawkException hawkException)
Purpose Constructor to create an instance of TraceException. • The first form creates an instance using the specified code and error string.
• The second form converts a HawkException to TraceException for the purpose of re-throwing the exception.
Remarks The error code creating an instance of TraceException must be in the legal ranges of HawkErrors and AmiErrors. When propagating (re-throwing) an exception caught from other TIBCO Hawk packages, you must use the second form of the constructor.
Parameters Parameter Description code The error code indicating the exception condition.
error The error text corresponding to this exception condition.
hawkException The existing exception to be converted.
See Also AmiErrors, page 42 HawkErrors, page 206 HawkException, page 152 ResourceException, page 161
TIBCO Hawk AMI Java Reference | 165
Chapter 9 Error and Debug Classes
The AMI Trace interface handles the error and debug functions of the TIBCO Hawk API interface. The TraceError and HawkError classes define specialized error codes for the TIBCO Hawk Java API.
Topics
• Trace, page 166 • AmiTrace, page 194 • TraceErrors, page 205 • HawkErrors, page 206
TIBCO Hawk AMI Java Reference 166 | Chapter 9 Error and Debug Classes
Trace Class COM.TIBCO.hawk.utilities.trace.Trace
Direct Known Subclasses
AmiTrace
Declaration public class Trace extends java.lang.Object
Purpose Instances of this class encapsulate the tracing context of a message logging engine. A trace object of this class has the following properties:
Property Description level The current trace level.
dirName The directory path where trace file are created.
fileName The name of trace file to log message to.
fileSize The maximum file length the trace file is allowed to grow to in Kilobytes.
maxFile The maximum number of trace files to keep before purging.
Remarks After an instance of this class is created, trace logging functions can be performed by using its trace methods. This class also provides a collection of get and set methods for retrieving and changing the tracing properties.
By using the Trace.log methods, messages are logged only if the specified trace level is set in the current trace context. The only exceptions are the ALWAYS and ERROR trace level. When these two trace levels are specified as the input trace code, the corresponding input message is logged, regardless of the state of the current trace level.
TIBCO Hawk AMI Java Reference Trace | 167
Trace file names should be named using the .log suffix. This is a recommendation, not a requirement. When setting a trace file name, the Trace.setFileName(String) method parses the input string and looks for the last "." character to determine the trace file name's prefix and suffix names. The prefix name of the specified trace file names is the set of characters, from the first character, up to but not including the "." character. The suffix name of the specified trace file names is the set of characters from the "." to the last character.
For example, trace file name sample.log is parsed into prefix name sample and suffix name .log. The purpose of the trace file prefix and suffix names is discussed below.
Trace file names, stdout and stderr (case insensitive) are special file names that correspond to standard output file descriptor and standard error file descriptors. When either of these two strings is used as trace file name, no actual file is created; the corresponding system stdout and stderr file descriptors are used instead. Messages are logged to the specified file name until the file length reaches a specified fileSize. The Trace.log methods rolls over the current trace file when it detects that the trace file has exceeded the limit indicated by fileSize. The rollover trace file name is computed as follows: 1. The current log file is renamed to file of the form
The Trace package keeps tracks of the next index number to be used when Trace.setDirectoryName(String) and/or Trace.setFileName(String) are called, when it scans the directory with matching prefix_index.suffix files. 2. If no existing trace files matches the prefix_index suffix format, then the index number starts at 001. When the index number reaches 999, it will be wrapped around back to 001.
To keep the number of trace files within the specified maxFile parameter, the Trace package deletes old trace file of the form {prefix_oldindex.suffix where oldindex is the current index minus maxFile.
Field public static final int ALL Declaration public static final int ALWAYS public static final int INFO
public static final int WARNING
public static final int ERROR
public static final int DEBUG
public static final int AMI
TIBCO Hawk AMI Java Reference 168 | Chapter 9 Error and Debug Classes
public static final int MIN_LEVEL
public static final int MAX_CODE_STRING_LENGTH
public static final long MIN_FILE_LENGTH
public static final long MAX_FILE_INDEX
public static final int DEFAULT_LEVEL
public static final java.lang.String DEFAULT_DIRECTORY_NAME
public static final java.lang.String DEFAULT_FILE_NAME
public static final long DEFAULT_MAX_FILE_LENGTH
public static final long DEFAULT_MAX_FILE_INDEX
public static final java.lang.String DEFAULT_DATE_TIME_FORMAT
Field Summary
Field Description
ALL Constant int value for turning on all trace levels.
ALWAYS Constant int value for indicating that text message coded with this value will always be logged to the trace file, no matter what the value of current trace level.
AMI Constant int value for indicating that text message coded with this value will be logged to the trace file if the current trace level is set with the bit AMI on.
DEBUG Constant int value for indicating that text message coded with this value will be logged to the trace file if the current trace level is set with the bit DEBUG on.
DEFAULT_DATE_TIME_FORMAT The default date time format string.
DEFAULT_DIRECTORY_NAME The default directory to create the trace files.
DEFAULT_FILE_NAME The default file name to log the trace statements.
DEFAULT_LEVEL The default trace level is ALWAYS.
DEFAULT_MAX_FILE_INDEX The default maximum number of trace file to keep before purging of old trace files.
TIBCO Hawk AMI Java Reference Trace | 169
Field (Cont’d) Description (Cont’d)
DEFAULT_MAX_FILE_LENGTH The default maximum trace file length before rollover is 1Mb - Although the user of this package may choose set this value to be as low as MIN_FILE_LENGTH, we recommend that the maximum trace file size not be set lower than this default for efficiency purpose.
ERROR Constant int value for indicating that text message coded with this value will be logged to the trace file if the current trace level is set with the bit ERROR on.
INFO Constant int value for indicating that text message coded with this value will be logged to the trace file if the current trace level is set with the bit INFO on.
MAX_CODE_STRING_LENGTH The maximum allowable string length of user defined trace code string.
MAX_FILE_INDEX The index field of the trace file is a fixed 3 digits integer which means the maximum index field is 999
MIN_FILE_LENGTH The minimum file length. MIN_FILE_LENGTH's unit of measurement is in Kilobytes.
MIN_LEVEL The minimum allowable integer values of this class.
WARNING Constant int value for indicating that text message coded with this value will be logged to the trace file if the current trace level is set with the bit WARNING on.
TIBCO Hawk AMI Java Reference 170 | Chapter 9 Error and Debug Classes
Member Summary Member Description Page
Trace.Trace() Creates an instance of Trace object. 172
Accessor Methods
Trace.getDirectoryName() Gets the current trace log directory path 174 name.
Trace.getFileName() Gets the current trace log file name. 175
Trace.getFileSize() Gets the current allowable maximum file 176 length.
Trace.getLevel() Gets the current trace level. 175
Trace.getLevelHelpString() Gets the help text corresponding to the 178 specified trace level.
Trace.getLevelLabelString() Gets the label string corresponding to the 179 specified trace level.
Trace.getLevelString() Gets the corresponding trace level string 175 of the specified trace level code.
Trace.getMaxFile() Gets the current maximum number of 179 rolled over file to keep.
Trace.getMaxLevel() Gets the current maximum settable level. 182
Trace.getNumberOfLevels() Gets the current number of distinct trace 186 levels.
Trace.getOutputStream() Gets the OutputStream object currently 182 used by this trace
Trace.isLevelOn() Returns whether a specified trace code 174 setting is on in the current Trace object
Logging Method
Trace.log() Logs the specified message or 186 exception according to the current trace properties.
Methods for Setting Parameters
TIBCO Hawk AMI Java Reference Trace | 171
Member (Cont’d) Description (Cont’d) Page Trace.setDateTimeFormat() Method for overriding the default date 186 time format string.
Trace.setDirectoryName() Set the current trace directory with the 188 specified path.
Trace.setFileName() Set the current trace file name with the 189 specified name.
Trace.setFileSize() Set the current allowable maximum file 190 length.
Trace.setLevel() Set the current trace level with the 186 specified int value
Trace.setMaxFile() Set the current allowable maximum 192 number of trace files.
Trace.setUserLevel() Sets the next available user definable 193 trace level.
TIBCO Hawk AMI Java Reference 172 | Chapter 9 Error and Debug Classes
Trace.Trace() Constructor
Declaration public Trace()
public Trace(Trace trace)
public Trace( int level, java.lang.String dirName, java.lang.String fileName, long fileSize, long maxFile) throws TraceException
Purpose Creates an instance of the Trace object.
• The first form creates an instance of the Trace object using default values.
• The second form creates an instance of the Trace object with an existing Trace object.
This constructor causes the Trace properties to be shared between the specified Trace object and the newly-created Trace object. No new log file is created. Tracing operations on the existing Trace object are equivalent to performing the operation on the new Trace object, and vice versa.
• The third form creates an instance of the Trace object using user-supplied parameters.
Remarks The specified fileName string should not include path string.
If the specified dirName is null, then the default directory name is used.
If the specified fileName is null, then the default file name is used.
If the specified fileSize is 0, then the default file size is used.
If the specified maxFile is 0, then the default max file is used.
Parameters Parameter Description
trace An existing Trace object.
level Trace level.
dirName Directory for creating trace files.
fileName File name used for creating trace file.
TIBCO Hawk AMI Java Reference Trace.Trace() | 173
Parameter (Cont’d) Description (Cont’d)
fileSize Maximum file length allowed before rollover.
maxFile Maximum number of files allowed until purging old files.
Throws TraceException. For possible raised exceptions, please see the following set methods.
See Also Trace.setDirectoryName(), page 188 Trace.setFileName(), page 189 Trace.setFileSize(), page 190 Trace.setMaxFile(), page 192
TIBCO Hawk AMI Java Reference 174 | Chapter 9 Error and Debug Classes
Trace.getDirectoryName() Method
Declaration public java.lang.String getDirectoryName()
Purpose Get the current trace log directory path name.
Returns Returns the current directory path.
TIBCO Hawk AMI Java Reference Trace.getFileName() | 175
Trace.getFileName() Method
Declaration public java.lang.String getFileName()
Purpose Get the current trace log file name.
Returns Returns the current file name.
TIBCO Hawk AMI Java Reference 176 | Chapter 9 Error and Debug Classes
Trace.getFileSize() Method
Declaration public long getFileSize()
Purpose Returns the current allowable maximum file length.
TIBCO Hawk AMI Java Reference Trace.getLevel() | 177
Trace.getLevel() Method
Declaration public int getLevel()
Purpose Returns the current trace level.
TIBCO Hawk AMI Java Reference 178 | Chapter 9 Error and Debug Classes
Trace.getLevelHelpString() Method
Declaration public java.lang.String getLevelHelpString(int code)
Purpose Returns the help text corresponding to the specified trace level.
Parameters Parameter Description code Trace level to query for help text.
TIBCO Hawk AMI Java Reference Trace.getLevelLabelString() | 179
Trace.getLevelLabelString() Method
Declaration public java.lang.String getLevelLabelString(int code)
Purpose Gets the label string corresponding to the specified trace level.
Parameters Parameter Description code Trace level to query for label string.
TIBCO Hawk AMI Java Reference 180 | Chapter 9 Error and Debug Classes
Trace.getLevelString() Method
Declaration public java.lang.String getLevelString(int code)
Purpose Gets the trace level string corresponding to the specified trace level code.
Remarks If the specified trace code does not exist (such as a user-defined trace level that has not been previously set by means of Trace.setUserLevel method), the string returned is null.
Parameters Parameter Description code Trace level code.
TIBCO Hawk AMI Java Reference Trace.getMaxFile() | 181
Trace.getMaxFile() Method
Declaration public long getMaxFile()
Purpose Gets the current maximum number of rolled over trace level files.
TIBCO Hawk AMI Java Reference 182 | Chapter 9 Error and Debug Classes
Trace.getMaxLevel() Method
Declaration public int getMaxLevel()
Purpose Gets the current maximum settable level.
Remarks This method differs from the trace level ALL, in that this method returns the current known maximum trace level. The maximum trace level can potentially change if the user sets additional user-defined trace levels.
TIBCO Hawk AMI Java Reference Trace.getNumberOfLevels() | 183
Trace.getNumberOfLevels() Method
Declaration public int getNumberOfLevels()
Purpose Gets the current number of distinct trace levels.
Returns The number of distinct trace levels.
TIBCO Hawk AMI Java Reference 184 | Chapter 9 Error and Debug Classes
Trace.getOutputStream() Method
Declaration public java.io.OutputStream getOutputStream()
Purpose Returns the OutputStream object currently used by this trace.
TIBCO Hawk AMI Java Reference Trace.isLevelOn() | 185
Trace.isLevelOn() Method
Declaration public boolean isLevelOn(int code)
Purpose Checks whether a specified trace code setting is on in the current Trace object
Parameters Parameter Description code A trace code to test.
Returns Returns boolean true if the current Trace object's trace code has the specified code set.
For example, if the current Trace object's trace setting is set with trace.setLevel(WARNING | ERROR | AMI);' then trace.isLevelOn(WARNING) would return true, whereas trace.isLevelOn(INFO) would return false.
TIBCO Hawk AMI Java Reference 186 | Chapter 9 Error and Debug Classes
Trace.log() Method
Declaration public void log( int code, java.lang.String msg)
public void log( int code, java.lang.Exception e)
public void log( int code, java.lang.String msg, java.lang.Exception e)
Purpose Logs the specified message according to the current trace properties. The first form logs the specified message according to the current trace properties. The second form logs the specified exception's stack trace according to the current trace properties. The third form logs the specified exception's stack trace, according to the current trace properties.
Parameters Parameter Description code If this specified code is turned on in the current trace property, the message is logged.
msg The message to log.
e The exception object to log.
TIBCO Hawk AMI Java Reference Trace.setDateTimeFormat() | 187
Trace.setDateTimeFormat() Method
Declaration public void setDateTimeFormat(java.lang.String format) throws TraceException
Purpose The is the method for overriding the default date/time format string.
Parameters Parameter Description format User-supplied format string to override the default date and time format string supplied in this class. This format string must conform to the SimplDateFormat class' date/time format string.
Throws TraceException is thrown if the specified format string is null.
TIBCO Hawk AMI Java Reference 188 | Chapter 9 Error and Debug Classes
Trace.setDirectoryName() Method
Declaration public void setDirectoryName(java.lang.String dirName) throws TraceException
Purpose Sets the current trace directory with the specified path.
Parameters Parameter Description dirName Directory path to be set.
Throws TraceException is thrown if one of the following is true: • Specified directory is null. • Specified directory does not exist. • Specified directory is not a directory. • Specified directory is not writable (no write permission). If the specified directory name is the same as the current directory path, no action is taken. If the specified directory is valid and is different from the current directory path, the new path is accepted; the new directory is read to find the latest index whose file name matches the current file name by _. If, in this new directory path, the file name / already exists, this file is rolled over to /_. This allows the user of this package not have to save existing log files.
See Also Trace.setFileName(), page 189
TIBCO Hawk AMI Java Reference Trace.setFileName() | 189
Trace.setFileName() Method
Declaration public void setFileName(java.lang.String fileName) throws TraceException
Purpose Sets the current trace file name to the specified name.
Remarks If the specified file name is stderr or stdout, no actual file is created. All trace log statements will be written to stderr and stdout, respectively. If the specified file name is the same as the current file name, no action is taken. Otherwise, the new file name is accepted, then parsed to derive the portion of the new file name up to but not including the last '.' character. The remainder of the new file name is the string of the rest of the file name. For example, if the specified file name is Trace.log, the first part would be Trace and the last would be .log. The files in the directory are then read and evaluated to derive the last index used, where file name matches the "_" format. The maximum number of all the matches in this format are used as the last index. If an existing file matches the specified file name, the existing file is renamed to "_" before the new file is created.
Parameters Parameter Description
fileName Name of the new file.
Throws TraceException is thrown if fileName is null.
TIBCO Hawk AMI Java Reference 190 | Chapter 9 Error and Debug Classes
Trace.setFileSize() Method
Declaration public void setFileSize(long fileSize) throws TraceException
Purpose Sets the current allowable maximum file length.
Remarks If the specified value is less than the current maximum value, the current trace file is not immediately rolled over. The trace file will be rolled over upon the next log statement where it detects that the current file length has exceeded the allowable maximum.
Parameters Parameter Description
fileSize The new allowable maximum file length in Kilobytes.
Throws TraceException is thrown if the specified fileSize is less than MIN_FILE_LENGTH.
TIBCO Hawk AMI Java Reference Trace.setLevel() | 191
Trace.setLevel() Method
Declaration public void setLevel(int level) throws TraceException
Purpose Sets the current trace level with the specified int value.
Parameters Parameter Description level A level value representation of the trace level.
Throws TraceException is thrown if the integer value is out of the legal range.
TIBCO Hawk AMI Java Reference 192 | Chapter 9 Error and Debug Classes
Trace.setMaxFile() Method
Declaration public void setMaxFile(long maxFile) throws TraceException
Purpose Set the current allowable maximum number of trace files.
Remarks If the new maximum is less than the current maximum, this method will purge files from the current directory to maintain the number of trace files at the new maximum.
Parameters Parameter Description
maxFile Maximum number of rolled over files to keep.
Throws TraceException is thrown if the specified maxFile is outside of the range of 1 and MAX_FILE_INDEX.
TIBCO Hawk AMI Java Reference Trace.setUserLevel() | 193
Trace.setUserLevel() Method
Declaration public int setUserLevel( java.lang.String user, java.lang.String help)
public int setUserLevel( java.lang.String user, java.lang.String label, java.lang.String help)
Purpose Sets the next available user-definable trace level. • The first form sets the next available user-definable trace level • The second form examines a static internal table to determine the next available user-definable trace level. The specified parameters, and the user, label, and help strings are associated with the available trace level and reserved in the internal table. The trace level code is then returned.
The difference between user and label strings lies in that input user strings are blank-padded to the maximum length of all known trace level strings. The label string is not blank padded.
Parameters Parameter Definition
user User defined trace level string.
label User defined trace level label string.
help User defined trace level help text.
TIBCO Hawk AMI Java Reference 194 | Chapter 9 Error and Debug Classes
AmiTrace Subclass COM.TIBCO.hawk.utilities.trace.Trace COM.TIBCO.hawk.ami.AmiTrace
Declaration public class AmiTrace extends Trace implements AmiTraceInterface, AmiEnabledInterface
Purpose This AmiTrace class implementation of the AmiTraceInterface allows a Java application to log messages to stderr, stdout or to a file. This AmiTrace class is a sub-class of Trace.
Fields inherited from class COM.TIBCO.hawk.utilities.trace.Trace ALL, ALWAYS, AMI, DEBUG, DEFAULT_DATE_TIME_FORMAT, DEFAULT_DIRECTORY_NAME, DEFAULT_FILE_NAME, DEFAULT_LEVEL, DEFAULT_MAX_FILE_INDEX, DEFAULT_MAX_FILE_LENGTH, ERROR, INFO, MAX_CODE_STRING_LENGTH, MAX_FILE_INDEX, MIN_FILE_LENGTH, MIN_LEVEL, WARNING
Methods inherited from class COM.TIBCO.hawk.utilities.trace.Trace getDirectoryName, getFileName, getFileSize, getLevel, getLevelHelpString, getLevelLabelString, getLevelString, getMaxFile, getMaxLevel, getNumberOfLevels, getOutputStream, isLevelOn, log, main, setDateTimeFormat, setDirectoryName, setFileName, setFileSize, setLevel, setMaxFile, setUserLevel, setUserLevel
Member Member Description Page Summary AmiTrace() Constructor. 196
Accessor Methods
AmiTrace.getMethods() Returns an array of AmiMethodInterfaces 197 for getting and setting AmiTrace properties.
Logging Methods
AmiTrace.logAlways() Logs trace information regardless of the state of 198 the trace properties.
AmiTrace.logAmi() Logs trace information only if the state of the 199 trace properties indicates a need for AMI debugging messages.
TIBCO Hawk AMI Java Reference AmiTrace | 195
Member (Cont’d) Description (Cont’d) Page AmiTrace.logDebug() Logs debug information. 200
AmiTrace.logError() Logs error information. 201
AmiTrace.logInfo() Logs information messages. 202
AmiTrace.logWarning() Logs warning messages. 203
Set Methods
AmiTrace.setSession() This method has a no-op implementation 204
TIBCO Hawk AMI Java Reference 196 | Chapter 9 Error and Debug Classes
AmiTrace() Constructor
Declaration public AmiTrace()
public AmiTrace(Trace trace)
public AmiTrace( int level, java.lang.String dirName, java.lang.String fileName, long fileSize, long maxFile) throws TraceException
public AmiTrace( int level, java.lang.String fileName, long fileSize, long maxFile) throws TraceException
Purpose Creates an instance of the class AmiTrace.
TraceException is thrown if any of the input arguments are invalid.
Parameters Parameter Description
trace An existing Trace object.
level The current trace level.
dirName The directory path to use for creating log files.
fileName The file name to use for create log file.
fileSize The maximum number of Kilobytes before file rollover.
maxFile The maximum number of files to keep.
TIBCO Hawk AMI Java Reference AmiTrace.getMethods() | 197
AmiTrace.getMethods() Method
Declaration public AmiMethodInterface[] getMethods() throws AmiException
Purpose Returns an array of AmiMethodInterfaces for getting and setting AmiTrace properties.
Remarks This method implements the AmiEnabledInterface such that an array of four AmiMethodInterfaces for getting and setting AmiTrace properties are returned.
The AmiMethodInterfaces returned by this method are:
• getTraceLevel
• setTraceLevel
• getTraceParameters
• setTraceParameters
Specified by getMethods in interface AmiEnabledInterface
TIBCO Hawk AMI Java Reference 198 | Chapter 9 Error and Debug Classes
AmiTrace.logAlways() Method
Declaration public void logAlways(java.lang.String logMsg)
public void logAlways(java.lang.Exception e)
Purpose Invoking this method logs the input logMsg, regardless of the state of the trace properties.
• When the first form is invoked, the input logMsg should always be logged, regardless of the state of the trace properties. • When the second form is invoked the input exception's stack trace should always be logged, regardless of the state of the trace properties.
Specified by logAlways in interface AmiTraceInterface
Parameters Parameter Description logMsg The message to be logged.
e The exception to be logged.
TIBCO Hawk AMI Java Reference AmiTrace.logAmi() | 199
AmiTrace.logAmi() Method
Declaration public void logAmi(java.lang.String logMsg)
public void logAmi(java.lang.String Exception e)
Purpose Creates a log entry only if the state of the trace properties indicates a need for AMI debugging messages.
• When the first form is invoked the input logMsg should be logged only if the state of the trace properties indicates a need for AMI debugging messages. • When the second form is invoked the input exception's stack trace should be logged only if the state of the trace properties indicates a need for AMI debugging messages.
Specified By logAmi in interface AmiTraceInterface
Parameters Parameter Description logMsg The message to be logged.
e The exception to be logged.
TIBCO Hawk AMI Java Reference 200 | Chapter 9 Error and Debug Classes
AmiTrace.logDebug() Method
Declaration public void logDebug(java.lang.String logMsg)
public void logDebug(java.lang.Exception e)
Purpose Logs debug information.
• When the first form is invoked, the input logMsg should be logged only if the state of the trace properties indicates a need for debugging messages. • When the second form is invoked, the input exception's stack trace should be logged only if the state of the trace properties indicates a need for debugging messages.
Specified By logDebug in interface AmiTraceInterface
Parameters Parameter Description logMsg The message to be logged.
e The exception to be logged.
TIBCO Hawk AMI Java Reference AmiTrace.logError() | 201
AmiTrace.logError() Method
Declaration public void logError(java.lang.String logMsg)
public void logError(java.lang.Exception e)
Purpose • When the first form is invoked, the input logMsg should always be logged, regardless of the state of the trace properties. • When the second form is invoked, the input exception's stack trace should always be logged, regardless of the state of the trace properties. This method logs errors, regardless of the state of the trace properties.
Specified By logError in interface AmiTraceInterface
Parameters Parameter Description logMsg The message to be logged.
e The exception to be logged.
TIBCO Hawk AMI Java Reference 202 | Chapter 9 Error and Debug Classes
AmiTrace.logInfo() Method
Declaration public void logInfo(java.lang.String logMsg)
public void logInfo(java.lang.String Exception e)
Purpose Logs input information.
• When the first form is invoked, the input logMsg should be logged only if the state of the trace properties indicates a need for information messages. • When the second form is invoked, he input exception's stack trace should be logged only if the state of the trace properties indicates a need for information messages.
Specified By logInfo in interface AmiTraceInterface
Parameters Parameter Description logMsg The message to be logged.
e The exception to be logged.
TIBCO Hawk AMI Java Reference AmiTrace.logWarning() | 203
AmiTrace.logWarning() Method
Declaration public void logWarning(java.lang.String logMsg)
public void logWarning(java.lang.String Exception e)
Purpose Logs warning information.
• When the first form is invoked, the input logMsg should be logged only if the state of the trace properties indicates a need for warning messages. • When the second form is invoked, the input exception's stack trace should be logged only if the state of the trace properties indicates a need for information messages.
Specified By logWarning in interface AmiTraceInterface
Parameters Parameter Description logMsg The message to be logged.
e The exception to be logged.
TIBCO Hawk AMI Java Reference 204 | Chapter 9 Error and Debug Classes
AmiTrace.setSession() Method
Declaration public void setSession(AmiSession ami) throws AmiException
Purpose This method has a no-op implementation.
Remarks The AmiTrace does not need the state of the AmiSession. This method therefore has no effect in this implementation.
Specified By setSession in interface AmiEnabledInterface
Parameters Parameter Description
ami The current AmiSession object.
TIBCO Hawk AMI Java Reference TraceErrors | 205
TraceErrors Class COM.TIBCO.hawk.utilities.trace.TraceErrors
Declaration public class TraceErrors extends java.lang.Object
Purpose The TraceErrors class defines a set of error codes unique to the TIBCO Hawk Java packages. This range of error codes has been registered with COM.TIBCO.hawk.utilities.exception.HawkException.
See Also HawkException, page 152
Field public static final int TRACE_INIT_ERR Declarations public static final int TRACE_NO_DIR_ERR
public static final int TRACE_NO_PERMISSION_ERR
Fields Field Error Code Description TRACE_INIT_ERR Initialization error.
TRACE_NO_DIR_ERR The specified directory does not exist.
TRACE_NO_PERMISSION_ERR Access is denied for the specified resource.
TIBCO Hawk AMI Java Reference 206 | Chapter 9 Error and Debug Classes
HawkErrors Class COM.TIBCO.hawk.utilities.exception.HawkErrors
Declaration public class HawkErrors extends java.lang.Object
Purpose Implements specialized TIBCO Hawk error codes.
Field public static final int HAWK_UNKNOWN_EXCEPTION_CLASS Declarations public static final int HAWK_ERROR_OUT_OF_RANGE
public static final int HAWK_NULL_POINTER_ERR
public static final int HAWK_INVALID_ARGUMENT_ERR
Field Summary Field Purpose
HAWK_ERROR_OUT_OF_RANGE Special error code reserved for HawkException to indicate that the programmer has attempted to generate an instance object of HawkException subclass with an out of range error code for the specified subclass.
HAWK_INVALID_ARGUMENT_ERR Error code to indicate that an invalid argument is encountered.
HAWK_NULL_POINTER_ERR Error code to indicate that a null object is encountered.
HAWK_UNKNOWN_EXCEPTION_CLASS Special error code reserved for HawkException to indicate that the programmer has attempted to generate an instance object of HawkException subclass, however, this subclass' class name and error code range are not registered with HawkException.
See Also HawkException.HawkException(), page 154
TIBCO Hawk AMI Java Reference | 207 Index
Symbols AmiMethod.getReturns() 52 AmiMethod.getSession() 53 .AmiAlertType 36 AmiMethod.getType() 55 AmiMethod.onInvoke() 56 AmiMethod.setIndexName() 57 AmiMethod.setSession() 58 A AmiMethodContext 71 AmiMethodContext.equals() 77 AmiAlertType.equals() 39 AmiMethodContext.getArguments() 74 AmiAlertType.fromString() 38 AmiMethodContext.getContext() 76 AmiAlertType.hashCode() 40 AmiMethodContext.getDuration() 73 AmiAlertType.toString() 37 AmiMethodContext.getMethod() 72 AmiAsyncMethod 59 AmiMethodContext.getReplySubject() 75 AmiAsyncMethod.AmiAsyncMethod() 60 AmiMethodContext.hashCode() 78 AmiAsyncMethod.onStart() 62 AmiMethodInterface 106 AmiAsyncMethod.onStop() 63 AmiMethodInterface.getArguments() 108 AmiAsyncMethodInterface 119 AmiMethodInterface.getHelp() 109 AmiAsyncMethodInterface.onStart() 120 AmiMethodInterface.getIndexName() 110 AmiAsyncMethodInterface.onStop() 121 AmiMethodInterface.getName() 111 AmiConstants() 41 AmiMethodInterface.getReturns() 112 AmiEnabledInterface 102 AmiMethodInterface.getSession() 113 AmiEnabledInterface.getMethods() 104 AmiMethodInterface.getTimeout 114 AmiEnabledInterface.setSession() 105 AmiMethodInterface.getType() 115 AmiErrors 42 AmiMethodInterface.onInvoke() 116 AmiException 159 AmiMethodInterface.setIndexName() 117 AmiException.AmiException() 160 AmiMethodInterface.setSession() 118 AmiGetVersionMethod 65 AmiMethodType 79 AmiGetVersionMethod.addComponentVersion() 66 AmiMethodType.equals() 82 AmiGetVersionMethod.getArguments() 67 AmiMethodType.fromString() 81 AmiGetVersionMethod.getIndexName() 68 AmiMethodType.hashCode() 83 AmiGetVersionMethod.getReturns() 69 AmiMethodType.toString() 80 AmiGetVersionMethod.onInvoke() 70 AmiParameter 88 AmiMethod 43 AmiParameter.AmiParameter() 90 AmiMethod.AmiMethod() 45 AmiParameter.getHelp() 92 AmiMethod.equals() 47 AmiParameter.getLegalChoices() 93 AmiMethod.getArguments() 48 AmiParameter.getName() 94 AmiMethod.getHelp() 49 AmiParameter.getValue() 95 AmiMethod.getIndexName() 50 AmiParameter.getValueChoices() 96 AmiMethod.getName() 51 AmiParameter.setLegalChoices() 97
TIBCO Hawk AMI Java Reference 208 | Index
AmiParameter.setValueChoices() 98 AmiTraceInterface.logInfo() 142 AmiParameterList 99 AmiTraceInterface.logWarning() 143 AmiParameterList.AmiParameterList() 100 AmiTraceInterface.setDirectoryName() 144 AmiSession 14 AmiTraceInterface.setFileName() 145 AmiSession.addMethod() 19 AmiTraceInterface.setFileSize() 146 AmiSession.addMethods() 20 AmiTraceInterface.setLevel() 147 AmiSession.announce() 21 AmiTraceInterface.setMaxFile() 148 AmiSession.getHelp() 23 AmiTraceInterface.setUserLevel() 149 AmiSession.getMaxThreads() 24 AmiSession.getMethod() 25 AmiSession.getMethods() 26 AmiSession.getName() 27 C AmiSession.getTrace() 28 AmiSession.sendData() 30 changes from the previous release x AmiSession.sendUnsolicitedMsg() 31 Class Hierarchy 10 AmiSession.setMaxThreads() 32 ComponentVersion 84 AmiSession.setSession() 34 ComponentVersion.getComponentInfo() 86 AmiSession() 17 ComponentVersion() 85 AmiTrace 194 customer support xv AmiTrace.getMethods() 197 AmiTrace.logAlways() 198 AmiTrace.logAmi() 199 AmiTrace.logDebug() 200 D AmiTrace.logError() 201 AmiTrace.logInfo() 202 Daemons and Agents 2 AmiTrace.logWarning() 203 AmiTrace.setSession() 204 AmiTrace() 196 AmiTraceInterface 122 E AmiTraceInterface.getDirectoryName() 126 AmiTraceInterface.getFileName() 127 Error and Debug Classes 165 AmiTraceInterface.getFileSize() 128 AmiTraceInterface.getLevel() 129 AmiTraceInterface.getLevelHelpString() 130 AmiTraceInterface.getLevelLabelString() 131 H AmiTraceInterface.getLevelString() 132 AmiTraceInterface.getMaxFile() 133 HawkErrors 206 AmiTraceInterface.getMaxLevel() 134 HawkException 152 AmiTraceInterface.getNumberOfLevels() 135 HawkException.getCode() 155 AmiTraceInterface.isLevelOn() 136 HawkException.getMax() 156 AmiTraceInterface.log() 137 HawkException.getMessage() 157 AmiTraceInterface.logAlways() 138 HawkException.getMin() 158 AmiTraceInterface.logAmi() 139 HawkException.HawkException() 154 AmiTraceInterface.logDebug() 140 AmiTraceInterface.logError() 141
TIBCO Hawk AMI Java Reference Index | 209
I Trace.getLevelString() 180 Trace.getMaxFile() 181 Interface Hierarchy 11 Trace.getMaxLevel() 182 Introduction 1 Trace.getNumberOfLevels() 183 Trace.getOutputStream() 184 Trace.isLevelOn() 185 Trace.log() 186 J Trace.setDateTimeFormat() 187 Trace.setDirectoryName() 188 Java AmiSession Class 13 Trace.setFileName() 189 Java Classes and Class Structure 9 Trace.setFileSize() 190 Trace.setLevel() 191 Trace.setMaxFile() 192 Trace.setUserLevel() 193 P Trace.Trace() 172 TraceErrors 205 Programmer’s Checklist 8 TraceException 163 TraceException.TraceException() 164
R
Resource Hierarchy 11 ResourceException 161 ResourceException.ResourceException() 162
S support, contacting xv
T technical support xv TIBCO_HOME xiii Trace 166 Trace.getDirectoryName() 174 Trace.getFileName() 175 Trace.getFileSize() 176 Trace.getLevel() 177 Trace.getLevelHelpString() 178 Trace.getLevelLabelString() 179
TIBCO Hawk AMI Java Reference