Tutorials


SendAgent

SendAgent allows the user to send messages interactively through a comprehensive GUI.
The source codes for this agent can be found in the directory \src\aglobe\src\examples\agent\send\.

  1. To send messages, we must have at least two SendAgents. To do that, we need to run one or more platforms that will host our agents.
    Go to the A-globe distribution directory (by default \dist\) and at the command line type the following:

    java -jar AGlobe.jar -name MyContainer -gui

    This will create an agent container named MyContainer.
    (Note that it's also possible to create more containers and place each of the agents on a different container.)

  2. Next, we'll create two agents on this container.
    (Note that more than two agents can be created as well.)

    To create an agent, open the File menu in the container window and select Load Agent.
    A dialog window will open. Fill in the following data:

    for the first agent:
    Name prefix:MyAgent1
    Main class:examples.agent.send.SendAgent

    for the second agent:
    Name prefix:MyAgent2
    Main class:examples.agent.send.SendAgent

    This will create two SendAgents named MyAgent1 and MyAgent2.
    Also, a GUI window will open for each SendAgent.


    (click to enlarge)

  3. As you can see, many of the parameters are already filled in with default values. All we have to specify now in order to send a message from one agent to another is to fill in the name of the receiver in the sender's GUI window.
    Let's assume that we want MyAgent1 to send a message to MyAgent2.
    Go to the GUI window of MyAgent2 and copy the parameter Sender > Name to clipboard (Ctrl+C). Then go to the GUI window of MyAgent1 and fill in the parameter Receiver > Name by pasting the clipboard content there (Ctrl+V).

    Now click on the Send button in MyAgent1's GUI window. MyAgent2 should report that it received a new message (see the Incoming Messages box).

 

MigratingAgent

MigratingAgent interactively demonstrates agents' ability to migrate across containers and platforms.
The source codes for this agent can be found in the directory \src\aglobe\src\examples\agent\migrating\.

  1. First, we must run several containers. To demonstrate the most common case, we'll create one master container and several slave containers. MigratingAgent will migrate across slave containers.
    Go to the A-globe distribution directory (by default \dist\) and at the command line type the following:

    java -jar AGlobe.jar -name MyMaster -master -gui
    java -jar AGlobe.jar -name MySlave1 -slave -gui
    java -jar AGlobe.jar -name MySlave2 -slave -gui
    java -jar AGlobe.jar -name MySlave3 -slave -gui

    This will create one master container named MyMaster and three slave containers named MySlave1, MySlave2 and MySlave3.

  2. Now we'll run a MatrixESAgent on the master container which controls migration rules.
    It is either possible to create this agent as any other agent (see Loading an Agent) or to use a menu command that is available in the master container toolbar for convenience.

    From the master container GUI toolbar, open the Environment Simulator menu and select Start ES Matrix Agent.

    This will create a MatrixESAgent on the master container.
    Also, a GUI window of the MatrixESAgent will open.

    Using this matrix, it is possible to control visibility between agent containers.
    An agent cannot migrate between containers that are not visible to each other.
    By default, all containers are visible.

  3. Next, we'll create a MigratingAgent on one of the slave containers.
    (Note that it is possible to create as many agents as you want.)

    Choose one of the slave container GUI windows (MySlave1, MySlave2 or MySlave3), open the File meno from the toolbar and select Load Library. In the dialog select '...' button and locate migratingagent.jar library stored in dist/ directory. Then press OK button to load the library into the A-globe. Open the File menu from the toolbar and select Load Agent.
    A dialog window will open. Fill in the following data:

    Name prefix:MyAgent
    Main class:examples.agent.migrating.MigratingAgent
    Libraries:select migratingagent.ver1@{container_name}

    This will create a MigratingAgent named MyAgent.
    Also, a GUI window of the MigratingAgent will open.

  4. To migrate the agent, choose the destination container (parameter Dest) and click on the Migrate button.
    If the destination container is visible from the current one, the agent will migrate and the container windows will update.

Notes:

 

Create the message content ontology

The example of send agent which uses its own ontology for sending messages is in the directory \src\aglobe\src\examples\agent\send2\. When creating your own message contant ontology, you need to go through the following procedure:

  1. First, we need a DTD (Document Type Definition) and a XJS file describing the ontology of the message content. The XJS file specifies how to represent elements and attributes in Java, e.g. whether an element is Integer or String. By default all non mentioned elements and attributes are handled as String. In our example we have a simple ontology Test with one String attribute Content. The DTD and XJS files are stored in the src/ subdirectory. A Document Type Definition example follows:

    <?xml version="1.0" encoding="UTF-8"?>
    <!ELEMENT Test EMPTY>
    <!ATTLIST Test
    	Content NMTOKEN #REQUIRED
    >

    and XJS:

    <?xml version="1.0" encoding="UTF-8"?>
    <!DOCTYPE xml-java-binding-schema SYSTEM "..\..\..\..\..\jaxb\xjs.dtd">
    <xml-java-binding-schema version="1.0ea">
    	<options package="examples.agent.send2"/>
    	<element name="Test" type="class" root="true">
    	</element>
    </xml-java-binding-schema>
    

  2. Now we'll compile the ontology into the source file for a Java class. The output package is specified in the XJS file. In our example the Java source for the ontology Test will be placed in the /examples/agent/send2/ directory. From that src/ subdirectory run:

    makejaxb Test

  3. Now the ontology Test is ready to be used. The compiled ontology provides a set of get... and set... methods for manipulating both attributes and elements values.

 

Demonstration of library management

We will demonstrate the library management in an example scenario containing one examples.agent.send.SendAgent and one examples.agent.send2.SendAgent. According to the A-globe default configuration, the package examples.agent.send is stored in the examples.jar library and the package examples.agent.send2 is stored in the send2.jar library. The first library is referenced from the CLASSPATH parameter of the Aglobe.jar manifest file. Its name space is therefore imported in the bootstrap class loader. The second library send2.jar must be loaded in A-globe before starting examples.agent.send2.SendAgent.

Proceed according to the SendAgent section. First, start an agent container. Next, create one SendAgent named Send1 using the New Agent dialog (main class examples.agent.send.SendAgent). There is no other SendAgent in the combo list now. Next, load the send2.jar library into the A-globe platform using the File/Load Library menu action (same procedure as in the MigratingAgent section). Next, create the second SendAgent named Send2 using the New Agent dialog (main class examples.agent.send2.SendAgent@...). After loading the send2.jar library, a new agent appears in the main class combo list with the library requirement indicated by its name coming after the character '@'. An agent Send2 cannot be created until the send2.jar library is selected in the library list.

The Test ontology that is used for sending messages from the Send2 agent is stored in the send2.jar library. When we send a message from Send2 agent to the Send1 agent (use the same procedure as in the section SendAgent), the Send1 agent will receive a warning message instead of a message content saying: Cannot deserialize message content: No class definition found: examples.agent.send2.Test. It's because the Send1 agent doesn't know content ontology class.

Now create another agent Send3 (main class examples.agent.send.SendAgent and select send2.jar library in the list). We can try to send a message from the Send2 agent to the Send3 agent. The Send3 agent receives the correct content, because it uses send2.jar library where the content ontology is defined.