----------------------------        
KraftMonitor (version 1.10)

Ted Francis.
Dept of Computing Science
University of Aberdeen

Written: 17th July 1998
----------------------------        


======
README
======

This file contains instructions for installing, compiling and running the 
*KraftMonitor visualisation tool* in conjunction with a Linda server and
Prolog clients within the KRAFT architecture

The Monitor traces communication taking place between KRAFT agents,
and displays this information to the user in a graphical way.  It is 
intended that this tool will be used as an aid to debugging existing 
KRAFT facilities, developing new ones, and demonstrating KRAFT in a 
more user-friendly manner.

The introduction of the Monitor has required some additions to
the Linda server code, and this is detailed below.


CHANGES from release 1.00
-------------------------
This release differs from the previous in the following ways:

-it allows monitoring of remote sites, via the Java-Linda gateway mechanism. 
 The gateway code has been adapted to allow this, detailed below

-the monitor can recognise 'register' performatives sent by other agents,
 this allows the agent to provide information about its role, resource type,
 etc, and this will affect the way it is graphically represented by the 
 Monitor.

-the monitor can read in 'batch' files of kraft_msg terms, and display them 
 to the user as if they had been sent by actual agents.

-It can also SAVE 'batch' files of the current activity being visualised.



How the Monitor works
---------------------
On starting up the Monitor connects to a Linda server, and "outs" a 
predicate of the form: 	
			monitor(<monitor_name>)  

This will instruct Linda to send <monitor_name> duplicates of any 
kraft messages that subsequently pass through it. 

The Monitor, if required will also monitor remote sites, in conjunction 
with its local site.  It achieves this by "outing" a predicate to its 
local Linda server of the form:  

			remote_monitor(on, <remote_site>, <monitor_name>)

The adapted Java gateway recognises this predicate, and routes it to
the gateway at <remote_site>. The remote gateway, on receipt of this, then
"outs" the 'local' monitor predicate to its Linda server:

			monitor(<monitor_name>)

The (remote) linda server then makes duplicate messages for <monitor_name>
as before.  The gateway routing mechanism can then deliver these messages 
back to the Monitor's site in the normal way.


NB: For correct monitoring of remote sites, the monitor *must* know the name
    of its local site (as well as those of any remote sites it wishes to 
    monitor).  This is so that <monitor_name> above can be of the form
    krl(<site>, <name>) so that gateways can successfully route messages 
    back to the Monitor.


-------------------

Linda, on receiving a kraft message ("outed" from a client), and 
seeing the presence of any "monitor" predicates, will wrap a copy 
of the original message into a properly formed CCQL 'forward' 
message destined to <monitor_name>, and "out" it to the 'blackboard', 
along with the original message.

The original message will be picked up by its intended receiver in 
the normal way.

The Monitor, like any other KRAFT facility, will be listening for 
messages to itself on Linda.  On receiving one, it will extract the 
original message from the 'forward' it receives.  It then displays 
this message graphically as an arrow passing between two red circles 
representing the sender and receiver of the message.

More detail about the message can be found by clicking in the centre of 
the arrow, and it can also be seen in the text area below.

As more messages are displayed, the user can step back and forth through
the messages by using the Prev and Next buttons.  The 'Mode' set 
determines whether the Monitor will not update its display until the user
presses 'next' (Step by Step mode), or whether it will update automatically 
when a new message is sent to the Monitor (Continuous mode).  The speed 
option affects the speed of automatic update.


Advantages
----------
- This architecture means that agents' activity can be monitored without
  the agents knowing of the presence of the Monitor.  So NO agent code 
  need be adapted to be 'monitorable', only the Linda server is adapted.

- Information destined for the Monitor can be delivered using the same 
  mechanism as all information in KRAFT, using Linda servers and/or 
  gateways, not via, e.g. another socket connection to each KRAFT agent.
 (also, although the number of messages passed through the 
  system is increased, it is only a linear increase, not an exponential one).

- As the Monitor deals with properly formed CCQL messages, there is room
  for expansion if more information needs to be communicated to it. The 
  Monitor would be 'seen' as a normal KRAFT agent by other agents.

  e.g. the Monitor could 'advertise' its location to a facilitator, so that
       agents could locate a Monitor, 'register' with it providing 
       some information about themselves.  All these messages would be 
       in the format already used within KRAFT.



-------------------
Directory structure
-------------------

kraft_linda-1.21     - **parent directory**
     |
     |
     |--monitor/        - this directory
	   |
	   |--classes/  -  contains .class files for all Java code
	   |		   (including Monitor/Linja/gateway)
	   |
	   |--src/      -  contains .java source files for Monitor code
	   |
	   |
	   |--docs/     -  contains javadoc (HTML) documentation for 
		           all monitor code (plus a list of the 
			   classes/methods in the gateway code)
			   (type netscape packages.html to view)

The commands given below are assumed to be from the parent directory 
kraft_linda-1.21, unless stated otherwise.


============
Instructions
============

1) Installing
2) Running
3) Compiling 
4) Changes to existing software



-------------
1) Installing
-------------

a) From **this** directory (monitor/).
   Type 'setenv CLASSPATH $cwd/classes' so the Java 
   virtual machine knows where to find all the Java code.


b) Set up the modified kraft-Linda library in the usual way:

(1.      change directory back to kraft_linda-1.21/)

2.      Edit "Makefile.inc" to tailor for your system, by setting the 
	correct paths for Prolog

3.      Compile the components by:

                make <platform_prolog>

        For example:

                make sgi_sicstus
        or      make sparc_quintus
        or      make sparc_sicstus
        or      make hp_sicstus


4.      Set up the environment variable HOST or HOSTTYPE to
	match your machine.

5.      Edit the file "prolog/machine_map.pl" to map your
        HOST or HOSTTYPE to the corresponding platform:

	host_map(<host_name>,<platform>)	



----------
2) Running
----------

a) Start a Linda server in a window:

			cd prolog/linda
			prolog
			
			| ?-  [linda_server].
			| ?-  linda.

b) Note the port number chosen by the Linda server from the line:
	"Server address is 'ip_address:port'"


c) In other windows, start some Prolog clients like this:
			
			cd prolog/messaging
			prolog

			| ?- [messaging].
			| ?- init_messaging([server_host:<hostname>, 
					     server_port:<port>]).


d) Start the Monitor by typing:

			java kraft.monitor.KraftMonitor


e) From the Monitor's menu bar, choose the Monitor->Setup menu, and 
   fill in the Monitor's name, Linda host and port. Click OK and the 
   Monitor will be ready to visualise any messages in the kraft_msg
   format that pass through the Linda server.


f) as a simple example with two prolog clients, client1 and client2:

   Client1:   | ?-   receive_message(client1, M).

   This will make client1 block, waiting to receive a kraft message

   
   Client2:   | ?-  compose_message(client2,client1,tell,
		    [sender:client2, receiver:client1, content:some_content],
		    M), send_message(M).

   This will make client2 send a simple message to client1.  You should 
   see that client1 does receive the message, AND the interaction has 
   been visualised by the Monitor.


g) For remote site monitoring
-----------------------------

	- start up a gateway for the linda_server as in previous versions:

			cd gateway
			java kraft.gateway.GatewayTest 
			    -c config_file -mn gateway_name 
			    -mp gateway_port -lh linda_host -lp linda_port 
	
	(some example config files are in kraft_linda-1.21/gateway)
	
	- ensure gateways and Linda servers are started for any 'remote' 		  sites you wish to monitor

	- From the Monitor-->Setup menu.  Set the monitor's details as before,
	  *including* the monitor's local site name, and the remote sites 
	  to be monitored (space or comma delimited).


	If clients now send messages to each other (remotely or locally),
	this will be visualised.



------------
3) Compiling
------------


All the Java code comes pre-compiled, but to re-compile everything, type
the following from the kraft_linda-1.21 directory:


   javac -d monitor/classes  Linja/*.java
		     	     gateway/*.java
	                     monitor/src/*.java
		     	     monitor/src/adapter/*.java
		    	     monitor/src/monitor/display/*.java
			     monitor/src/monitor/tools/*.java

   NB: run this twice to ensure full compilation takes place

-------------------------------
4) Changes to existing software
-------------------------------

The files that have been added/adjusted to incorporate the Monitor
with Linda are shown below


FILE		  DIRECTORY:

linda_server.pl   kraft_linda-1.21/prolog/linda/
messaging.pl      kraft_linda-1.21/prolog/messaging/
message_format.pl kraft_linda-1.21/prolog/messaging/
transport.pl      kraft_linda-1.21/prolog/messaging/		     


The Linda files have been modified as follows:

linda_server.pl - takes into account the "monitor" predicate,
                - duplicates messages in kraft_msg format to the Monitor
		- uses 'message_format' module to produce properly-
		  formed kraft_msg tuples when making these duplicates


messaging.pl   - This still provides the original Messaging API
   		 (user should not have to use the 2 modules below)
	       
	       - separated original file into three: 'messaging.pl', 
		 'message_format.pl' and 'transport.pl'.
               - done so that linda_server module could make use of the 
	         'message_format' module without having access to 'transport'


message_format.pl - provides properly formed kraft_msg tuples to
		    the above two modules

transport.pl     - provides transport mechanism for 'messaging' module 




The most significant changes to the Gateway code are in the file:

kraft_linda-1.21/gateway/SocketGateway.java


It has been modified to recognise the "remote_monitor" predicate, route
it correctly, and "out" "monitor" predicates appropriately
Icon  Name                    Last modified      Size  Description
[TXT] README 1998-07-17 18:41 11K [DIR] classes/ 2002-01-29 14:48 - [DIR] docs/ 2002-01-29 14:48 - [DIR] src/ 2002-01-29 14:48 -