## 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 `SendAgent`s. 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 `SendAgent`s 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:

- As it was mentioned above, it is also possible to restrict container visibility using the `MatrixESAgent` running on the master container.

- Agents can migrate even between platforms (computers). It is highly recommended to turn all firewalls off in that case.

#### 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.