The AMI API facilitates the development of AMI applications written in the Java, C++, and C programming languages. This API makes AMI application development easier and more foolproof because it takes care of AMI transport details for you. The API also ensures that your application will be compatible with future releases of TIBCO Hawk and AMI.
The AMI session handles the AMI application's entire interaction with the AMI manager. Each AMI session manifests itself as a microagent in the associated AMI manager. The API provides AMI manager with functions, which the AMI manager can invoke, to create the session, announce it, stop it, and also to exchange data, events, and errors with the AMI session.
A method can return data and or perform a task. An AMI application consists of a set of AMI methods that can be invoked by an AMI manager to monitor and manage the AMI application. AMI methods can accept input parameters and return output parameters as required by the method. AMI method provides functions to create and add AMI methods to specific AMI session. The AMI session announces AMI methods (sends their descriptions to an AMI manager) and detects invocations of your AMI methods.
An AMI method can be synchronous or asynchronous. A synchronous AMI method returns data only when invoked by an AMI manager. An asynchronous AMI method can return data whenever data becomes available.
Whenever an AMI manager invokes a synchronous AMI method, the AMI API will call an invocation callback function. You define the invocation callback functions for the synchronous AMI methods. The AMI API provides the callback function with the values of any input parameters and a mechanism for returning either output parameter values or an error. The invocation callback can return data, return no data, or return an error condition.
For asynchronous AMI methods, an AMI manager informs the AMI method when it should start or stop sending data. The asynchronous AMI method can define callback functions that the AMI API calls whenever an AMI manager has requested the AMI method to start or stop sending data. The AMI API provides the start callback function with a unique context (a subscription object) which identifies the start request, the values of any input parameters, and a mechanism for returning an error. The start callback routine can attach user data to the subscription object. If the start callback function does not return an error then the subscription is in effect and the asynchronous AMI method is free to return data at any time. Using the subscription object, the asynchronous AMI method can return data or error notifications asynchronously to the AMI manager. If the start callback function returns an error the AMI manager cancels the subscription. The AMI API provides the stop callback function with the subscription object and a mechanism for returning an error. The stop callback function can perform any necessary application cleanup. When the stop callback returns the AMI manager stops (cancels) the subscription.
There are two techniques that you can use to implement asynchronous methods. One technique is calling
AmiAsyncMethod::sendData() for a subscription whenever new data becomes available. The AMI method, AMI method input parameters and any attached user data can always be obtained from the subscription object and output parameters can be constructed using the AMI parameter functions discussed below. Using the start and stop callback functions you must keep track of subscriptions. There can be multiple simultaneous subscriptions to a single asynchronous AMI method, potentially, from multiple AMI managers. Subscription handles are guaranteed to be unique among active subscriptions within the same AMI session and can, therefore, be used as an index for tracking purposes. This technique is often used when a separate thread is created to service each subscription.
The other technique is calling AmiAsyncMethod::onData() for a method whenever new data becomes available. This function will call the invocation callback function of the associated method once for each active subscription to that method. The invocation callback function is passed the subscription object allowing the callback to get any attached used data necessary to process the new data. This technique allows the AMI API to do all the work of tracking subscriptions requiring your application to simply provide the invocation callback. The invocation callback can return data, return no data, or return an error condition. If data is returned, it is sent asynchronously to the AMI manager. If no data is returned then no action takes place. This allows the invocation callback function to decide whether the new data should be returned for the subscription. If an error is returned, then it is sent asynchronously to the AMI manager.
Depending on your specific method, this technique may also eliminate the need to supply a start and stop callback. If the subscription object passed to the invocation callback function is null (zero), then the method is being called synchronously. You may return data or an error depending if synchronous invocation is supported by your asynchronous method.
The AMI API provides a mechanism for creating auto-invoke asynchronous methods. During the start asynchronous method callback, the application can set an auto-invoke callback interval for the subscription. If an auto-invoke callback interval is set, the AMI API will call the invocation callback function repeatedly for the method at the specified interval until the subscription is stopped. This can be used to turn a synchronous method into a pseudo-asynchronous method, eliminating the need for the AMI manager to repeatedly invoke the synchronous method. Typically, a method argument is defined to allow the user to specify the interval.
This functionality is critical for synchronous methods that require some setup such as priming counters used to calculate averages, deltas, or percents. Synchronous methods are required to return data on each invocation, making it impossible to return correct data for return values requiring two or more samples on the first invocation. The auto-invoke asynchronous method can return data whenever it is ready. It also has a start and stop callback to perform setup and clean-up operations, respectively. Since the invocation callback function has the option of returning no data, it can skip invocations. This is useful when many data samples are required before accurate data can be returned, or when perhaps it is waiting for some required service to initialize.
AMI methods accept input parameters and return output parameters. The AMI API provides functions to define input and output parameters for an AMI method, to set and get the values of those parameters. The API allows settings of multiple values for output parameters allowing multiple (tabular) instances to be returned. If multiple instances (rows) of output parameters are returned then certain output parameters must be defined as indexes. These index parameters must have unique values across output parameter instances returned. If more than one index parameter is defined then the defined indexes are considered a composite index with the primary index specified first.
The AMI API functions can detect and return AMI errors. The AMI error is an object that identifies the specific error and contains handle-based functions that create, destroy, and file stamp AMI errors. The file stamp records a file name and line number in the AMI error to indicate the error source location. Functions are also provided to get the error code, error description, thread ID, file name, and line number associated with the specific AMI error.
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).
The AMI API is multi-thread safe and uses multiple threads internally (to guarantee timely processing of AMI protocol related functions). However, it does not impose a threading model on your AMI application. You are free to use the AMI API in a single or multi-threaded application.
