The TIBCO Hawk Console API is partitioned along the functional lines of monitoring and management. At the root is the TIBHawkConsole class from which you can access the
AgentMonitor and
AgentManager, which encompass the monitoring and management facilities of the API.
All monitoring is performed using event notification. Listeners are registered with the AgentMonitor for the type of monitoring required and the relevant status messages are delivered as events when they are detected.
A registered listener for a particular type of event will receive notifications for all monitored agents that generate that event. For example, registering a AgentMonitorEventLister with the console will allow it to receive
AgentMonitorEvents for all agents known to the console, thus allowing it to track the alive or expired status of every agent.
The most basic type of monitoring is the monitoring of agent existence. This is achieved by registering an AgentMonitorListener with the
AgentMonitor. When you register an
AgentMonitorListener, it will receive one agent-alive event for every agent the console can detect.
An agent-alive event is actually represented by the delivery of an AgentMonitorEvent to the on
AgentAlive() method of the listener. This event contains a reference to an
AgentInstance object which identifies which agent it pertains to. As new agents appear in the network, new agent-alive events will be generated to identify them. When the console is no longer able to communicate with an agent, it will issue an agent-expired event for that agent. This is performed by delivering a
AgentMonitorEvent to the on
AgentExpired() method of the listener. As before, this event contains a reference to an
AgentInstance object which identifies which agent it pertains to. The console can lose communication with an agent for several reasons, for example if the agent process is no longer running, the machine it was running on has crashed, or because of a problem in the underlying communications infrastructure such as a network outage.
To perform this type of monitoring you simply register a MicroAgentListMonitorListener with the
AgentMonitor. Events of type
MicroAgentListMonitorEvent are then delivered to either the
onMicroAgentAdded() or
onMicroAgentRemoved() method of the listener. The event contains an
AgentInstance object, which identifies the agent, and a
MicroAgentID object, which identifies the microagent.
To perform this type of monitoring you register a RuleBaseListMonitorListener or
onRulebaseUpdated with the
AgentMonitor. Events of type
RuleBaseListMonitorEvent are then delivered to either the
onRuleBaseAdded() or
onRuleBaseRemoved() method of the listener. The event contains an
AgentInstance object, which identifies the agent, and a
RuleBaseStatus object, which is used to identify the rulebase being added or removed.
The onRulebaseUpdated() listener provides an atomic update callback for rulebase update events. To receive
onRulebaseUpdated(), implement
ExtendedRuleBaseListMonitorListener as per the definition provided in
API Reference section.
Every alert is associated with a particular rulebase and every rulebase is associated with a particular agent. (Technically, rulebases are said to be associated with the RuleBaseEngine microagent instance registered with that agent, therefore the association with the agent is indirect.) The alert state of a rulebase will always be highest alert state of all the active (non-cleared) alerts associated with it. The alert state of an agent (or its
RuleBaseEngine microagent) is the highest alert state of any of its currently loaded rulebases. Therefore, alerts and clears can potentially change the state of the rulebase and agent that generated them.
Alert monitoring is performed by registering an AlertMonitorListener with the
AgentMonitor. Alerts and clears generated by an agent are detected by the console and delivered as
AlertMonitorEvent objects to the listener. Since
AlertMonitorEvent is an abstract class, one of its concrete subclasses is delivered:
PostAlertEvent for alerts and
ClearAlertEvent for clears.
Every AlertMonitorEvent contains flags that indicate whether it caused a change in the state of the
RuleBaseEngine or the rulebase it is associated with. It also holds the current states of those objects after taking into account the current event. Other attributes include an alert ID, which uniquely identifies an alert, and the time the event was generated.
Because AlertMonitorEvent extends
AgentMonitorEvent, it also has an
AgentInstance attribute to identify the agent that generated the event.
The PostAlertEvent class extends
AlertMonitorEvent and adds the state of the alert and the alert text. The
ClearAlertEvent class extends
AlertMonitorEvent and adds the reason-cleared text. This string identifies the reason the alert was cleared.
All alert states are represented as integer values that are mapped using the AlertState interface. A
PostAlertEvent with a state of
AlertState.NO_ALERT is also called a notification.
If a console client is interested in tracking agent status across agent instances or console agent instances then it may do so using the console agent ID, that is, the AgentID class. If a agent is restarted several times (without changing its ID attributes) then this will result in the creation of several distinct instances of
AgentInstance in the console. These different instances, however, will all have equal
AgentID values to reflect the fact that they all relate to the same logical agent. Note that these multiple instances of
AgentInstance will never be referenced simultaneously by the console. This is because the console will never hold two
AgentInstance objects with equal
AgentID attributes at any one time.
Management functions are performed by invoking management operations on microagents. As described in Microagent List Monitoring, each agent contains a collection of objects called microagents. Microagents have methods through which all monitoring and management is performed. Microagents represent managed entities such as the operating system's subsystems, log files, event logs, applications, and even the agent itself.
The AgentManager class is used to interact with microagents. An instance of this class is obtained by invoking the
getAgentManager() method of the
TIBHawkConsole class.
Descriptors are represented by the MicroAgentDescriptor class. They are obtained by invoking the
describe() method of the
AgentManager class. A
MicroAgentDescriptor fully describes a microagent. It contains a list of
MethodDescriptor objects that describe each available method and all that is needed to invoke them.
•
|
IMPACT_ACTION: Methods of type IMPACT_ACTION take some action that can potentially change the state of the managed object represented by the microagent.
|
•
|
IMPACT_INFO: Methods of type IMPACT_INFO simply retrieve some information in a manner that does not change the state of the managed object.
|
•
|
IMPACT_ACTION_INFO: Methods of type IMPACT_ACTION_INFO return data but may also change the sate of the managed object.
|
The describe() method of the
AgentManager requires an argument of type
MicroAgentID. There are two general ways to obtain
MicroAgentID objects:
•
|
The method AgentManager.getMicroAgentID() can also be used to obtain MicroAgentID objects. It takes a microagent name as its argument and returns an array of all microagents of that name that are currently loaded on all agents the console can communicate with. This method blocks for a period of time while it queries the agents on the network. A second version of this method accepts an integer that indicates the minimum number of desired microagent ids in the return. This method generally returns more quickly than the first version if the minimum number specified is less than or equal to the actual number of matching microagents on the network.
|
Microagent methods are invoked using the invoke() method of the
AgentManager. This method takes a
MicroAgentID and a
MethodInvocation object. The
MicroAgentID may be obtained as described in
Microagent Descriptors. The
MethodInvocation can be constructed using the data provided in the microagent descriptor.
Method invocations return an instance of the MicroAgentData class, which acts as a container for transmitting invocation results.
MicroAgentData objects contain source and data attributes. The source attribute is a
MicroAgentID object identifying the source of the data. The data attribute contains the actual method invocation results.
If the method invocation is successful, the data field of its MicroAgentData return will contain the method's return value or null if the method doesn't return a value.
The AgentManager also allows you to register a subscription for microagent methods with its
subscribe() method. Registering for a subscription is analogous to registering for an event. It results in a continuous stream of
MicroAgentData return values from the method being subscribed to. This data is asynchronously delivered to a
SubscriptionHandler object supplied during registration.
In addition to a SubscriptionHandler, the
subscribe() method of
AgentManager requires a
MicroAgentID, to identify the target, and a
MethodSubscription object.
The MethodSubscription class extends the
MethodInvocation class. A
MethodSubscription should be constructed in accordance with the
MethodDescriptor of the target method.
Registering a subscription returns a Subscription object that can be used to cancel the subscription and to examine how the subscription was created
You can use either of two constructors to build a MethodSubscription, depending on whether you are creating a subscription for a synchronous or asynchronous method. The
MethodDescriptor for a method indicates whether the method is synchronous or asynchronous. An asynchronous method is analogous to an event source. Listeners that subscribe to an asynchronous method will receive the method's declared return value each time a particular event occurs.
The MethodSubscription constructor for synchronous method subscriptions requires an interval parameter. It is used to specify a desired subscription service rate. Subscriptions made of synchronous methods will use this value as a hint to determine how often to deliver data to service a subscription. Most microagents will usually enforce a minimum rate, which will be used if the supplied value is below their minimum.
The MethodSubscription constructor for asynchronous method subscriptions does not accept an interval parameter. Asynchronous methods deliver data at a rate determined by the microagent, typically, whenever it is available.
Group operations are performed with the groupOp() method of the
AgentManager. They are very similar to method invocations. The difference is that they require an array of
MicroAgentID targets and return an array of
MicroAgentData values.
•
|
<hawkDomain> is what would be used as the hawkDomain parameter of the TIBHawkConsole constructor if you were instantiating a console that communicates with all agents. If an agent is configured without a hawkDomain specification, it uses the value "default".
|
•
|
<agentDNS> should match the agentDNS (also called agent domain) parameter with which the agent was configured. If the agent was not configured with an agentDNS, it uses the value "none".
|
Refer to HAWK_HOME/examples/console_api/TestConsoleSSL.java for a sample java program to demonstrate a console test application which uses SSL parameters to connect to SSL.
The COM.TIBCO.hawk.agent.nest package is used to write TIBCO Hawk microagents that run inside the agent. To run as a microagent in the TIBCO Hawk agent, an object must implement either the
MicroAgent or
ServiceMicroAgent interface. Note that this package is dependent on the
COM.TIBCO.hawk.console.talon package.