Package COM.TIBCO.hawk.console.hawkeye

Class AgentManager

java.lang.Object
COM.TIBCO.hawk.console.hawkeye.AgentManager
All Implemented Interfaces:
MicroAgentServer
public class AgentManager extends Object implements MicroAgentServer
The AgentManager is used to monitor TIB/Hawk agent events.

The AgentManager itself is both thread-safe and thread-aware.

Using the AgentManager Class

The correct general procedure for using the AgentManager class is:

  1. call initialize() to initialize the AgentManager
  2. perform any desired management activities
  3. call shutdown() when done

  • Constructor Details

    • AgentManager

      public AgentManager(String hawkDomain, String rvService, String rvNetwork, String rvDaemon)

    • AgentManager

      public AgentManager(String hawkDomain, String serverURL, String clientId, String userName, String password, Hashtable environment)

    • AgentManager

      public AgentManager(String hawkDomain, String serverURL, Hashtable environment)

    • AgentManager

      public AgentManager(String hawkDomain, String host, int port, int tunnelMode)

    • AgentManager

      public AgentManager()

    • AgentManager

      public AgentManager(Map config)

  • Method Details

    • initialize

      public void initialize(String securityImpl, int securityMode) throws ConsoleInitializationException
      Initializes a secure AgentManager.

      The securityImpl parameter identifies the class file that implements the security policy.

      The securityMode parameter signals the contex of the invoker. Possible contexts are HsConsoleInterface.WINDOW, HsConsoleInterface.CONSOLE, and HsConsoleInterface.DAEMON. WINDOW indicates an interactive windowing environment. It is possible to perform interactive activities from within this context. CONSOLE indicates an interactive console session. It is also possible to perform interactive command-line activities from within this context. DAEMON indicates a non-interactive batch or background process. It is not possible to perform interactive activites from within this context.

      See the TIB/Hawk Programmer's Guide for information on security policy implementation and security context.

      Parameters:
      securityImpl - the name of the class implementing the security policy.
      securityMode - the context of the invoker.
      Throws:
      ConsoleInitializationException - If some initialization error occurred

    • initialize

      public void initialize(Object securityObj, int securityMode) throws ConsoleInitializationException
      Initializes a secure AgentManager.

      The securityImpl parameter identifies the class file that implements the security policy.

      The securityMode parameter signals the contex of the invoker. Possible contexts are HsConsoleInterface.WINDOW, HsConsoleInterface.CONSOLE, and HsConsoleInterface.DAEMON. WINDOW indicates an interactive windowing environment. It is possible to perform interactive activities from within this context. CONSOLE indicates an interactive console session. It is also possible to perform interactive command-line activities from within this context. DAEMON indicates a non-interactive batch or background process. It is not possible to perform interactive activites from within this context.

      See the TIB/Hawk Programmer's Guide for information on security policy implementation and security context.

      Parameters:
      securityObj - the security object implementing the interfaces HsConsoleInterface and HsAgentInterface
      securityMode - the context of the invoker.
      Throws:
      ConsoleInitializationException - If some initialization error occurred

    • initialize

      public void initialize() throws ConsoleInitializationException
      Initializes an AgentManager.
      Throws:
      ConsoleInitializationException - If some initialization error occurred

    • shutdown

      public void shutdown()
      Used to gracefully shutdown the AgentManager. Returns the AgentManager to an uninitialized state. Calling this method more than once has no effect.
      Specified by:
      shutdown in interface MicroAgentServer

    • describe

      public MicroAgentDescriptor describe(MicroAgentID id) throws MicroAgentException
      This method may be used to retrieve a descriptor for a microagent. The descriptor describes the microagent and all of its methods. It is required in order to properly construct and perform method invocations and subscription against a microagent.

      Specified by:
      describe in interface MicroAgentServer
      Parameters:
      id - The microagent id of the microagent to describe.
      Returns:
      A descriptor for the named microagent or null if the descriptor is not available.
      Throws:
      IllegalArgumentException - If the argument is null or empty string
      MicroAgentException - If a problem occurred servicing this request

    • invoke

      public MicroAgentData invoke(MicroAgentID id, MethodInvocation mi) throws MicroAgentException
      Performs a method invocation on a microagent.

      The results of the invocation are delivered in the data field of the MicroAgentData return.

      There are two general types of errors that can occur with method invocations:

      1. During the delivery of a method invocation to, or the results back from, a microagent. This condition will cause this method to throw a MicroAgentException.
      2. During the invocation of the method on the microagent itself. This condition will cause this method to deliver a MicroAgentException in the data field of the MicroAgentData return.

      Thus, a successful method invocation is one that doesn't throw an exception and does not deliver a MicroAgentException in the data field of its MicroAgentData return.

      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.

      You should not invoke to methods that are non-open (proprietary) unless you have supporting api and documentation. Doing so will have unpredictable results. Whether or not a method is open is defined by its MethodDescriptor

      Specified by:
      invoke in interface MicroAgentServer
      Parameters:
      id - The microagent id of the target microagent.
      mi - The MethodInvocation object identifying the method to be invoked and its arguments. May not be null.
      Throws:
      IllegalArgumentException - If the parameter conditions are violated
      MicroAgentException - If an error occurs during the delivery of a method invocation to, or the results back from, a microagent.

    • subscribe

      public Subscription subscribe(MicroAgentID id, MethodSubscription msub, SubscriptionHandler handler, Object handBack) throws MicroAgentException
      Registers a subscription with a microagent.

      Subscriptions are made against microagent methods. Registering a subscription is analogous to registering for events, where a microagent's method is the event source.

      The subscribed to data is delivered asynchronously to the supplied SubscriptionHandler.

      There are two general types of errors that can occur with method invocations:

      1. During the registration of the subscription. This condition will cause this method to throw a MicroAgentException.
      2. During the servicing of the subscription These errors are delivered to the SubscriptionHandler
      Specified by:
      subscribe in interface MicroAgentServer
      Parameters:
      id - The microagent id of the target microagent.
      msub - Identifies what is being subscribed to.
      handler - The object that handles subscription results.
      handBack - This Object parameter is accessable in the resulting Subscription object which is delivered to the handler along with subscription results.
      Returns:
      a Subscription object that can be used to cancel the subscription and to examine how the subscription was created. This object is also passed to the SubscriptionHandler methods as the subscription is being serviced.
      Throws:
      IllegalArgumentException - If the parameter conditions are violated
      MicroAgentException - If an error occurs during the registration of the subscription.

    • getMicroAgentIDs

      public MicroAgentID[] getMicroAgentIDs(String microAgentName) throws MicroAgentException
      Queries all agents to learn the id of all microagents matching the supplied name.

      Returns a list of MicroAgentID objects identifying all microagents, bearing that name, that were discovered to be running on all agents.

      Note: If your application is also using the AgentMonitor to track agents and their microagents then it is more efficient to use the data supplied by the AgentMonitor rather than this method.

      Specified by:
      getMicroAgentIDs in interface MicroAgentServer
      Parameters:
      microAgentName - The microagent name.
      Throws:
      MicroAgentException - if an error occurs while satisfying the request.

    • getMicroAgentIDs

      public MicroAgentID[] getMicroAgentIDs(String microAgentName, int minNum) throws MicroAgentException
      Queries all agents to learn the id of microagents matching the supplied name.

      This version is faster than the other if the number of actual matching microagents on the network is greater than or equal to the supplied minNum value.

      Note: If your application is also using the AgentMonitor to track agents and their microagents then it is more efficient to use the data supplied by the AgentMonitor rather than this method.

      Specified by:
      getMicroAgentIDs in interface MicroAgentServer
      Parameters:
      microAgentName - The microagent name.
      minNum - The minimum number of microagents you want to discover.
      Throws:
      MicroAgentException - if an error occurs while satisfying the request.

    • getMicroAgentIDs

      public MicroAgentID[] getMicroAgentIDs(String agentName, String agentDns, String hawkDomain, String microAgentName, int minNum) throws MicroAgentException
      Queries specific agents to learn the id of microagents matching the supplied name.

      The first thre parameters (agentName, agentDns, and hawkDomain) identify the target agent(s). Any or all of these can be null to indicate a wildcard. Setting all three to null has the same effect as calling AgentManger.getMicroAgentIDs(String, int).

      Specified by:
      getMicroAgentIDs in interface MicroAgentServer
      Parameters:
      agentName - The name of the targeted agent. Use null or empty-string to match any agent name.
      agentDns - The dns value of the targeted agent. Use null or empty-string to match any dns value.
      hawkDomain - The hawkDomain of the targeted agent. NOTE: Currently, each instance of AgentManager is bound to a single hawk domain. Therefore, using any value other than that specific domain, null, or empty-string will return without discovering any agents.
      microAgentName - The microagent name.
      minNum - The minimum number of microagents you want to discover. Use zero to discover all available microagents (subject to a timeout interval).
      Throws:
      MicroAgentException - if an error occurs while satisfying the request.

    • groupOp

      public MicroAgentData[] groupOp(MicroAgentID[] targets, MethodInvocation mi) throws MicroAgentException
      Performs a group operation.

      Invokes the supplied method invocation on all target microagents.

      Specified by:
      groupOp in interface MicroAgentServer
      Parameters:
      targets - The list of MicroAgentID objects identifying which microagents to perform the invocation on.
      mi - The MethodInvocation object identifying the method to be invoked and its arguments. Cannot be null.
      Throws:
      MicroAgentException - if an error occurs while satisfying the request.