Package COM.TIBCO.hawk.talon

Interface MicroAgentServer

All Known Subinterfaces:
MicroAgentContainer
All Known Implementing Classes:
AgentManager
public interface MicroAgentServer
The MicroAgentServer interface.

MicroAgentServer objects are used to interact with an agent's microagents.

  • Method Details

    • describe

      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.

      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

      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

      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

      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
      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

      MicroAgentID[] getMicroAgentIDs(String name) throws MicroAgentException
      Queries the MicroAgentServer 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.

      Parameters:
      name - The microagent name.
      Throws:
      MicroAgentException - if an error occurs while satisfying the request.

    • getMicroAgentIDs

      MicroAgentID[] getMicroAgentIDs(String microAgentName, int maxNum) throws MicroAgentException
      Throws:
      MicroAgentException

    • getMicroAgentIDs

      MicroAgentID[] getMicroAgentIDs(String agentName, String agentDns, String hawkDomain, String microAgentName, int maxNum) throws MicroAgentException
      Throws:
      MicroAgentException

    • groupOp

      MicroAgentData[] groupOp(MicroAgentID[] targets, MethodInvocation mi) throws MicroAgentException
      Throws:
      MicroAgentException

    • shutdown

      void shutdown()