This tutorial describes the step-by step procedure of setting up the infrastructure and working with Moses toolkit. The purpose of this tutorial is to have the user able to communicate using LGI messages and to be comfortable to handling and observing the effects of LGI laws.

Prior to following this tutorial the user should have the Moses toolkit installed properly according to the installation procedures.

Runtime components

There are several steps one has to follow when attempting a message exchange using LGI:

• Choosing a set of controllers. Controllers are the servers that mediate the communication between LGI agents. The SEC Laboratory maintains a controller manager running a number of such controllers for public use (see the online system). However, due to the lack of administrative personnel for such an infrastructure , we strongly recommend the users to start their own controllers. This tutorial shows how to start and work with a single controller, created by the user, in her own environment.
• Choosing a law . Every message exchanged using the Moses toolkit is subject to a specific law. A law is most often referenced by a URL to a file containing the text of the law. Users developing and using their own laws can use any HTTP server in order to publish them. Moses toolkit also provides a small footprint HTTP server, called the Law Server . A separat tutorial on how to use this tool can be found here.
  
  This tutorial uses two laws that are published and maintained by our infrastructure. Each of them is presented both in Java and Prolog. More laws can be found at the example page.
• Using an LGI agent . Any program that uses the Moses Java-based API for communication becomes an LGI agent. Alternativelly, one can use a web-based agent in order to initiate simple web-based exchange of LGI messages. This tutorial first covers the simple case of using web-based interaction then it describes the case of programmed agents .

Starting a controller

After installing the Moses toolkit, obtain a console, or command line terminal and issue:

> java moses.Controller

This command will start the controller with the default parameters. In order to check that the controller has been started succesfully, verify the console for any error messages. Access the controller web interface by pointing your browser to:

http://hostname:8500

Where hostname represents the hostname where the controller has been started. If the machine is a Windows machine and does not have a DNS name, then take the full computer name from Control Panel/System Properties/Network Identification. A web page similar to the one in Figure 1) will be accessible. This page presents general information about the controller.

Human interface (web-based interraction)

Once the controller has been started properly, human actors can connect to the controller and start exchanging messages. The simplest way to do so is via the web-based interface provided by the controller. This interface is an applet that connects back to the controller and that provides the actor with a GUI for message exchange. In order to start the web based actor, use a Java-enabled browser to connect to the controller, as above, then click on the link "Create Agent/Connect to Controller". A dialog similar to the one in Figure (2) will appear:

In order for the actor to connect to the controller, a number of parameters should be supplied:

• The URL of the law. In order to test the connectivity and the communication through Moses toolkit, we consider a trivial law called simple law . This law is implemented both in Java and Prolog as follow:

  
  law(simple,language(java))
  
  import java.util.*;
  import java.io.*;
  
  public class simple extends Law{
  
          public void sent(String source, String message, String dest) {
           doForward();
          }
  
          public void arrived(String source, String message, String dest) {
           doDeliver();
          }
  
          public void disconnected() {
           doQuit();
          }
  }
  
  

  
  law(simple,language(prolog)).
  
  sent(X,M,Y) :- do(forward). 
  
  arrived(X,M,Y) :- do(deliver).
  
  disconnected :- do(quit).
  
  

  This law simply forwards all the messages sent by an agent and delivers them to the destination, unchanged. In some sense this is the simplest law possible.
  In the corresponding field of the agent connection window type in either http://www.moses.rutgers.edu/examples/simple/simple.java1 or http://www.moses.rutgers.edu/examples/simple/simple.law for a Prolog law.
• A preferred name for the agent: this is a user choice, but it should be unique with respect to this controller. Type in "smith";
• All the other fields can be left blank.

After typing Enter, a window similar to the one in Figure 3) should appear.

The communication interface presents a number of controls. Among them, the most important at the beginning are:

• the recipient represents the destination where to send a message. The name of the destination is composed of the name of an agent (e.g. smith) the character '@' and the host name of the controller the agent is connected to. In order to send a message to itself, fill out this field with "smith@hostname".
• the message to send to the destination. Fill in here with "testmessage".
• the send button triggers the sending of the message towards the destination. Press this button after filling the other fields as directed before.
• the lowest (traffic) text area displays the incoming and outgoing messages. In this case, since the agent smith sent a message to itself, the following information should appear in this area:

  dir | to/from | time | message
  ------------------------------
  OUT| smith@research.rutgers.edu | 10:42:18 | testmessage
  IN | [smith@research.rutgers.edu,simple] | 10:42:18 | testmessage
  

If this is what you see, then congratulations!!! This is the first LGI-message you've ever sent. Try to send various messages and observe the behavior.
In order to become familiar to exchanging messages via LGI, we illustrate bellow the following aspects of communication: sending messages between two different agents, sending messages between two agents connected to two different controllers, and the use to fancier laws.

Communication between two different agents

After creating agent "smith", follow the procedure at the beginning of the section in order to launch another agent, connected to the same controller. For this, open another browser window and browse to the connecting window. Choose a name for the second agent, e.g. "john" (make sure that the name is different than the first agent's name), and choose the same law as you have chosen for the first agent. Try to send a message from the first agent to the second and the other way around.

Communication between agents connected to different controllers

If you have another computer available, then you can start another controller on the second computer. If required, repeat the installation procedure and setting up the Moses toolkit on the second computer, then start another controller with the same port as the first controllers (controllers communicate with each other using the same port).

After the controller on the second machine is started, open up a browser (on any computer within the reach of the second computer) and browse this controller main page. Follow the instructions above to create an agent. After reaching the communication window, try to exchange messages between the agents connected to the first controller and the newly created agent.

Communication using a non-trivial law

In order to observe the behavior of a law that provides any control at all, take the slight modification of the previous laws:

law(fancier,language(java))

import java.util.*;
import java.io.*;

public class fancier extends Law{

        public void sent(String source, String message, String dest) {
         if(!message.equals("ping"))
                doDeliver("controller","notallowed",Self);
         else
                doForward();
        }

        public void arrived(String source, String message, String dest) {
         doDeliver();
        }

        public void disconnected() {
         doQuit();
        }
}

law(fancier,language(prolog)).

sent(X,ping,Y) :- do(forward). 
sent(X,M,Y) :- do(deliver(controller,notallowed,Self)). 

arrived(X,M,Y) :- do(deliver).

disconnected :- do(quit).

These laws, presented in Java and Prolog respectively, provide message filtering. Any message that is not "ping" is rejected and the source is informed that the message is not allowed. The "ping" message passes to any destination unrestricted.

Following the steps above, create two agents that operate under the new law. The URL for the new law is http://www.moses.rutgers.edu/examples/fancier/fancier.java1 (Java) or http://www.moses.rutgers.edu/examples/fancier/fancier.law (Prolog).
Using the new agents, try to send various messages between the agents. Observe that only the "ping" message is propagated.

The example section provides a number of laws that offer a more meaningful control and show some powerful LGI constructs.

Interaction through programmed actors

Once familiar to the interaction through human interface, it is relatively easy to set up a communication between programmed actors. The code bellow exemplifies the interaction, and a brief description follows:

import moses.member.*;
import moses.util.*;

public class SimpleAgent{
    public static void  main (String[] args) throws Exception {

    Member m =
         new Member(
	          "http://www.moses.rutgers.edu/examples/simple/simple.java1",
	          Const.URL_LAW,
		  "hostname",
		  9000,
		  "john");

    System.out.println( m.adopt("somepassword","somearguments"));	  

    m.send_lg("testmessage", m.longName);

    String ans0 = m.receive_lg();

    System.out.println("received: "+ans0);

    }
}

Several classes part of the Moses package are required: they are the member and util sub-packages. All the LGI communication is done through the Member class. The constructor initializes the agent and is provided with the (already familiar) URL of the law, the controller host name, the controller port, and the agent chosen name. An additional argument -- Const.URL_LAW -- specifies that the law argument is to be interpreted as an URL and not as immediate text.
After the Member object is constructed, the agent connects to its controller by calling the adopt() method. This method has a password and an optional String argument. If successful, this call returns a -1.
After connection to the controller is established, the agent can send and receive messages using send_lg(message,destination) and receive_lg(). In this example, the destination is the actor itself.

A simple variation of the example above can be found at http://www.moses.rutgers.edu/examples/simple/SimpleAgent.java

Compile this example using:
> javac SimpleAgent.java

and run it using
> java SimpleAgent http://www.moses.rutgers.edu/examples/simple/simple.java1 controllerHost controllerPort agentName

The output shows a number of messages arriving at the agent:

> java SimpleAgent
http://www.moses.rutgers.edu/examples/simple/simple.java1 research.
rutgers.edu 9000 john
Usage: java SimpleAgent lawURL controllerHost controllerPort agentname
-1
received: arrived([john@research.rutgers.edu,simple],testmessage0,john@research.rutgers.edu)
received: arrived([john@research.rutgers.edu,simple],testmessage1,john@research.rutgers.edu)
received: arrived([john@research.rutgers.edu,simple],testmessage2,john@research.rutgers.edu)
received: arrived([john@research.rutgers.edu,simple],testmessage3,john@research.rutgers.edu)
received: arrived([john@research.rutgers.edu,simple],testmessage4,john@research.rutgers.edu)
received: arrived([john@research.rutgers.edu,simple],testmessage5,john@research.rutgers.edu)
received: arrived([john@research.rutgers.edu,simple],testmessage6,john@research.rutgers.edu)
received: arrived([john@research.rutgers.edu,simple],testmessage7,john@research.rutgers.edu)
received: arrived([john@research.rutgers.edu,simple],testmessage8,john@research.rutgers.edu)
received: arrived([john@research.rutgers.edu,simple],testmessage9,john@research.rutgers.edu)

A number of programmed agents are presented in the example section. An in-depth description of the programming agent can be found in the documentation page. In the same place can be referenced the Javadoc API for a number of classes exposed to the programmer when working with agents and laws.