So, you got the
and think: "What exactly is in that agentopia.jar archive?"
In this section, I explain how the
framework is structured.
On programming advice for your own agents, head over to the
The first thing to note is that no RMI, no CORBA or
other hardwired protocol is used:
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
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
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