The Agent Launch API

The final option for launching an Agent is to write a program that calls into the Agent Launch API. The following example launches the DBAccessAgent with the same parameters as above.

 1: /*  DBAccessLaunch.java

 2:  *  Copyright © 1997 Horizon Systems Laboratory,

 3:  *  Mitsubishi Electric Information Technology Center America.

 4:  *  All rights reserved.

 5:  *

 6:  *  CONFIDENTIAL AND PROPRIETARY PROPERTY OF MITSUBISHI ELECTRIC ITA.

 7:  *

 8:  *  DESCRIPTION

 9:  *  Launcher for DBAccessAgent.

10:  *

11:  */

12: 

13: import COM.meitca.concordia.*;

14: 

15: public class DBAccessLaunch {

16: 

17:     public static void main(String args[])

18:         throws Exception {

19: 

20:  	    // First we construct the agent 

21:         DBAccessAgent agent = new DBAccessAgent("Europe");

22: 

23: 	    // Second we set up the Agents itinerary. Notice that 

24: 	    // we can specify the method to call by name.

25: 	    Itinerary agentItinerary = new Itinerary();

26: 	    agentItinerary.addDestination(new Destination("dbserver", "queryDatabase"));

27: 	    agentItinerary.addDestination(new Destination("workstation", "reportResults"));

28: 

29: 	    // We attach the Itinerary to the Agent using the setItinerary method

30: 	    agent.setItinerary(agentItinerary);

31: 

32: 	    // Third set up the URL pointing to the Agents codebase. 

33: 	    agent.setHomeCodebaseURL("http://mywebserver/Agents");

34: 

35: 	    // Fourth, we specify a list of classes which should travel with

36: 	    // the agent 

37: 	    String relatedClasses[] = {"QueryResult"};

38: 	    agent.setRelatedClasses(relatedClasses);

39: 

40:  	    // Last, we actually launch the agent by calling

41: 	    // its launch method

42:  	    agent.launch();

43:    }

44: 

45: }

Figure 6 - Example Agent Launch Code

Programmatically launching an Agent is accomplished by calling the Agent's launch method (line 42). Before calling launch, the programmer should build an Itinerary for the Agent and populate the Itinerary with Destinations using the Itinerary.addDestination method (lines 25-27). In constructing a Destination, the programmer should specify the hostname of the machine to visit and name of the method to invoke at the host. The hostname and method name are specified as Strings. The Itinerary is bound to the Agent using the Agent's setItinerary method (line 30).

Also prior to launching, the programmer can specify the Agent's codebase URL via the Agent.setHomeCodebaseURL method (line 33) and specify the related class list using the Agent.setRelatedClasses method (lines 37-38). The classes in the related class list should be specified as fully package qualified names and should be specified as Strings.

If any errors occur during the launching of the Agent, launch will throw an exception of class LaunchException. The message contained within the LaunchException will have more information about why the launch failed. The primary causes for LaunchException are network errors, down servers, or problems retrieving the bytecodes from the Agent's codebase.