So, you got the download, and think: "What exactly is in that agentopia.jar archive?" In this section, I explain how the Agentopia framework is structured. On programming advice for your own agents, head over to the FAQ section.

The first thing to note is that no RMI, no CORBA or other hardwired protocol is used: Agentopia uses just plain serialized objects and their class bytecode, transmitted via modified ObjectInputStream and ObjectOutputStream over TCP/IP connections, and then a custom ObjectClassLoader to load agent bytecode and instance dynamically, with little privileges (file system access, network I/O etc are forbidden for agents).

Consider the network structure in the UML class diagram below, starting with the Host to the middle left.

A concrete Host implements the IAgentopiaHost interface, meaning that it provides methods to network, and is bound to a specific home id (address and port, e.g. "agentopia.sf.net:15907"). A host holds a number of IAgentopiaConnection (see to the right of Host), which are able to transfer agents.

A Sustainer is a permanent TCP/IP connection between two hosts, where a ping packet ("ball") is sent back and forth, and occasionally an agent if required. This is the usual networking method. A Communicator is a one-time TCP/IP link, used for just one transfer; it is used as a shortcut.

The host loops on a server socket and waits for incoming connections or agents. Whenever one arrives, the Host creates a new ConnectionInputHandler (see top right of Host) to handle the incoming data, transmitting any results to an IMarketPlace (see next UML class diagram), which is created and held by the Host.

You will also notice that Host has the method jumpStart(agent); this is what you will use to get an agent going. Whichever the connection method, every agent arrives in the ConnectionInputHandler and finally at the IMarketPlace place shown in the UML class diagram below (middle left).

On the left, you see the Host holding an IMarketPlace instance. The host is strictly about networking; the market place is all about agent handling. A market place is split in two access levels: Agents see only the IMarketPlaceForAgents part, only the owner of the Host sees the full IMarketPlace. Have a look at the methods of the latter the see why this might be a good idea.

On the right, you see the market place holding several IAgentopiaServiteur and IAgentopiaAgent. For implementation convenience, abstract superclasses for concrete implementations are provided. A serviteur is mostly about service methods and the ability to browse, search and run those services; complementary, agents consume those services.

Agents are run in two stages, "activity" and "result": The former is executed on any host when the agent has not reached its goal yet, the latter when the agent arrives back home to present its result. Interaction on any host is mostly done through the IMarketPlaceForAgents, which can provide access to the serviteurs. Convenience methods enable reading messages from home (for interactive agents like the Remote Walker) and retrieve treasures from other hosts.

Finally, consider the core package of Agentopia in the UML class diagram below, consisting of two annotations and a lot of constants.

All agents must have the AgentopiaAgentMarker annotation, and all serviteurs must have the AgentopiaServiteurMarker annotation. Both are just markers (in the same sense as java.io.Serializable) so that no class is mistakenly used as agent or serviteur.

The right side shows a selection of events on an Agentopia host: message flags for sucess and failure, action flags for started or stopped hosts, markets, agents, serviteurs and exits (Sustainer or Communicator), and debug flags for network and market place components.

With this, you have a good overview of what is there; and if you want to know how to actually program your application with Agentopia, head over to the FAQ section for more.