Magenta v0.20 README
Last updated November 21, 2001
===========================================================================

This document is http://magenta.sourceforge.net/magenta011/README and can be 
obtained from http://magenta.sourceforge.net.  See the RELEASE file in this
same directory for information about what has changed since the last release.
See the COPYING file in this directory for licensing information

Please send questions or comments to alokem@NOSPAMrogers.com. (remove the word 
NOSPAM).  A mailing list for Magenta-related announcements, news and discussion 
is available.  See http://magenta.sourceforge.net/ for details.

Note: Magenta v0.20 requires Java version 1.2 or greater.

This distribution is composed of

magenta020/
	contains this file, RELEASE and COPYING

magenta020/magenta/
	core magenta files

magenta020/magenta-user/
	example Agent extensions and files for demo

magenta020/up2p-server/
	helper files for running a up2p server - read the README
	in this directory for more information

Installation
===========================================================================

1. Unpack the zip file.  This will create the magenta020 directory and
   subdirectories as described above.

2. Add the magenta020 directory to your classpath.  You will also need to
   add the magenta020/magenta-user directory to your classpath to run the
   demos.
   (you can add paths on the command-line using java's -cp option)

3. Change to the magenta subdirectory and compile all .java files
   (javac *.java)

4. Change to the magenta-user subdirectory and compile all .java files

5. Quick test: 
   Type "java magenta.CLIManager" at the command line and the prompt
   "localhost:4444%" should appear.  Type "quit" to exit.

More details about setting your classpath in windows:
http://java.sun.com/products/jdk/1.2/docs/tooldocs/win32/classpath.html
for solaris/linux:
http://java.sun.com/products/jdk/1.2/docs/tooldocs/solaris/classpath.html


A Simple Demo
===========================================================================

This demo relies heavily on the CLIManager, an example of a command-line driven 
Agent derived from magenta.Agent.  Read more about it and see the command 
reference at http://magenta.sourceforge.net/cgi-bin/wiki.pl?MagentaCLI.  

The demo uses the CLIManager to illustrate several important Magenta features: 
message passing, remote object creation and remote event notification.

Open three separate windows.
(Windows: DOS windows, Unix: xterms,  MacOSX: under the MacOSX "Terminal" 
 application).

In window one:
% java magenta.CLIManager
This will start a CLIManager - an example of an enhanced Magenta Agent which 
includes an interface for command-line interaction.  You should see the prompt 
"localhost:4444%" which indicates that this agent is listening on port 4444 of 
localhost.  From now I'll refer to this agent as "Agent 4444".

In window two:
% java magenta.Agent localhost:4445
This will start a basic Magenta Agent which has no interface.  I'll call this 
"Agent 4445".

In window three:
% java magenta.CLIManager localhost:4446
You should see the prompt "localhost:4446%".  I'll call this "Agent 4446".

At the prompt of window three enter the following command:
localhost:4446% root print
log: root [class: magenta.CLIManager name: root HostInfo: localhost:4446] ::

This is a listing of the objects contained in the current CLIManager (which is 
inherited from magenta.Agent).  There is only one object called "root" which is 
a pointer to ourselves (Agent 4446).  Note that the command "root print" can be 
read as follows: send the message "print" to the AgentProxy (or 
AgentProxy-derived object) called "root" in the local database - i.e. send the 
message "print" to *ourselves*.

Enter all the following commands at the console of Agent 4446 (window three).

1. create an AgentProxy representing the Agent 4445.  (required to communicate 
with it)
root create*magenta.AgentProxy*root*4445
root set*root/4445*HostInfo*localhost:4445

2. add Agent 4444 as an observer of Agent 4445 (i.e. add an AgentProxy object 
into Agent 4445's database under root/observers)
root/4445 create*magenta.GdmoObject*root*observers
root/4445 create*magenta.AgentProxy*root/observers*4444
root/4445 set*root/observers/4444*HostInfo*localhost:4444

3. create a printer in Agent 4445's database.  
localhost:4446% root/4445 create*Printer*root

On the console of Agent 4444 (window one) you should see the following:
localhost:4444% 
localhost:4444 event: *localhost:4445*magenta.AgentProxy*
root/observers/4444*HostInfo*localhost:4444
localhost:4444 event: *localhost:4445*Printer*root/Printer0*Instantiated*true

The first event is a result of step 2 (it was triggered when setting the 
HostInfo).  The second event marks the creation of the Printer object in the 
database of Agent 4445.  


N-Queens Demo
===========================================================================

The N-Queens problem is the problem of placing N chess queens on a chessboard 
with dimensions N x N such that none of the queens threaten each other.  In this 
example, each queen is implemented as a Magenta Agent interacting with each 
other directly.  The queens initially learn about eachother via a central 
n-queens server which also handles displaying the action.  Read more about the 
problem and this implementation at 
http://magenta.sourceforge.net/cgi-bin/wiki.pl?NQueensProblem

All of the objects, including other agents, are instantiated from the CLI 
illustrating that the CLIManager doubles as an Magenta Agent launcher.  
To start the CLI:

% java magenta.CLIManager

At the prompt enter the following commands:

1. Create the central server (Nqueens) and assign it a host:port to listen on.  
This will also start the chessboard representation (NqueensViewer).
root create*Nqueens
root set*root/Nqueens0*HostInfo*localhost:1500

2. Create four Queen objects.
root create*Queen
root create*Queen
root create*Queen
root create*Queen

3. Assign a unique host:port for each Queen to listen on.
root set*root/Queen0*HostInfo*localhost:2000
root set*root/Queen1*HostInfo*localhost:2001
root set*root/Queen2*HostInfo*localhost:2002
root set*root/Queen3*HostInfo*localhost:2003

4. Tell each queen how to contact the server (the Nqueens object).  This will 
"wake up" each queen and they will start reacting to each other's positions.
root set*root/Queen0*ServerInfo*localhost:1500
root set*root/Queen1*ServerInfo*localhost:1500
root set*root/Queen2*ServerInfo*localhost:1500
root set*root/Queen3*ServerInfo*localhost:1500

5. Cross your fingers and hope that the Queens settle into a steady state which 
is a solution to the N-queens problem.  As of this version this is not 
guaranteed by any means although I *have* seen it happen.  Feel free to improve 
though!

===========================================================================
The End.