Since those agents which currently wish to determine the state of a cell contact the cell's ServerEventInfoAgent to listen to the event stream, it seemed appropriate for the AgentMonitoringAgent to be built on top of the current ServerEventInfoAgent thereby replacing it with another agent of more functionality (while still trying to preserve the same interface for those agents still relying on the ServerEventInfoAgent).
The current ServerEventInfoAgent simply extends the EventSendingAgent with no other additional functions. When an agent subscribes to the the ServerEventInfoAgent, the agent will receive a stream of ServerEvents which notify the listener of the changes in state from the cell.
This is obviously not enough to get the complete state of all the agents on a server. If an agent wants this information, it first needs to query the RemoteServer interface via the queryAgents method (with null as both the syntactic and semantic descriptions) -- this will return a list of all the agents on the cell. It then needs to enumerate through this list asking all the agents to list their connections through the listAllConnections method.
The above method of getting a cell's agent population state is convoluted and difficult. In order to manage the states of many different cells, this process needs to be repeated many times. The ability to get the cell's event stream needs to be preserved when this agent is augmented, however a cleaner interface to the cell's state needs to also be provided.
ServerEvents will be broadcast for all the cells that this agent is monitoring (it may not emit certain events if it may cause a ServerEvent loop to be formed). When subscribing to this agent's event stream, by default all the ServerEvents will stream through, however an event mask will be also supported allowing the agent to subscribe to certain types of ServerEvents or to events that are being emitted from a particular server.
Agents need to be able to ask the AgentMonitoringAgent to monitor the state of other Hive cells by the cell's address. It should also be simple to get a list of the servers this agent is monitoring.
A simple interface to retrieve a list of agents -- the query parameters should be similar to the RemoteServer's queryAgents method, except one of the parameters needs to also be an array of CellAddresses. This will allow us to get a list of agents and also restrict the search by the location of the agents.
Another simple method call to get a data structure describing the agent connections.
This agent should be able to cache information about the agents on the other cells this agent is monitoring and be able to present this information to any other agent who wishes this information(it must be understood that there may be cache coherency problems). Candidates for caching are the CellAddress, the RemoteServer, the agent's description, the agent's icon, and a list of the other agent's this agent is connected to.
CellAddress[] getMonitoredCells(Object requester);
void monitorCell(Object requester, CellAddress toMonitor);
boolean isMonitoringCell(Object requester, CellAddress isMonitoring);
These functions are the proposed interface to control the monitoring of others cells in Hive. Through these commands, the AgentMonitoringAgent will start or stop monitoring the state of agents on other cells.
void addListener(EventReceivingAgent subscriber);
void addListener(EventReceivingAgent subscriber, CellAddress[] cellsToListenTo);
void addListener(EventReceivingAgent subscriber, long eventMask);
void addListener(EventReceivingAgent subscriber, CellAddress[] cellsToListenTo, long eventMask);
void removeListener(EventReceivingAgent toRemove);
The first addListener will subscribe the agent to all the ServerEvents coming from the AgentMonitoringAgent. These events will be concerning agents on all the different cells that the AgentMonitoringAgent is monitoring. The rest of the addListener variants are to filter certain ServerEvents -- by containing an array of CellAddresses or an ORed value of the event codes from ServerEvent, then an agent can ask the sender to only send particular events to it and not be flooded with ServerEvents that it does not care about.
DescSet queryAgents(Object requester, CellAddress[] addresses, String[] syntatic, String[] semantic);
DescSet listAllAgents(Object requester, CellAddress[] addresses);
AgentGraph listAllConnections(Object requester, CellAddress[] addresses);
DescSet listOutgoingAgentConnections(Object requester, Agent agent);
DescSet listIncomingAgentConnections(Object requester, Agent agent);
Using this API, agents can get retrieve a cell's agent population's state from the AgentMonitoringAgent. The queryAgents method works exactly the same way the RemoteServer's method except now the query can happen across many different cells (the listAllAgents method is just an alias for calling queryAgents with a null value for the syntatic and semantic fields). The CellAddress array is treated the same way as the other arrays -- if passed in as null then it is treated as a wildcard. listAllConnections returns an AgentGraph which encapsulates the connection structure between agents on the requested cells in this directed graph data structure. listOutgoingAgentConnections will list all the connections from this agent to other agents, and its companion function listIncomingAgentConnections lists all incoming connections to this agent.
int getEventLogLength(void);
int setEventLogLength(Object requester, int length);
ServerEvent[] getEventLog(Object requester, int n);
These methods provide access to the log of the ServerEvents that the AgentMonitoringAgent is keeping.
CellAddress getCellAddress(Agent agent);
RemoteServer getRemoteServer(Agent agent);
Description getDescription(Agent agent);
PPM getIcon(Agent agent);
These methods will provide information to agents so they do not need to query the agent itself directly. All these methods simply provide the same information their counterparts inside Agent would provide, but without calling the agent directly.