com.unet.warmachine.peerlocator
Class Agent

java.lang.Object
  |
  +--com.unet.warmachine.peerlocator.Agent

public class Agent

extends java.lang.Object

This class is the agent that locates other members of the group on behalf of its client. An agent does not provide a messaging service - clients are expected to establish their own connection and protocols once a member is located. An agent is created with suitable configuration and a list of known members. The agent must appear as a member of the list, although the list can be otherwise empty. The agent is created in a shutdown state and must be started using startup. Once started, it attempts to locate other (known) members of the group. For performance reasons, only a limited number of members will be searched at any one time, starting with members that use static IP addresses. Agents will inform each other of other members that have been located. Once a connection is established to the remote agent representing a member, the member is considered online. The client is notified whenever another member of becomes online or offline.

Clients can set their status value which is then broadcast to all other (online) members. This status value has no meaning to agents, only to their clients.

The agent also handles registration, which requires the IP address or range and TCP port no of a known member of the group. Registration is successful if the agent name does not clash with any other member. The location of new members is broadcast to other members. Note that as agents aren't in constant communication, a successfully registered name can be later rejected by another agent as it clashes with a another, known member.

This class is the overall system controller. It receives messages, decides how to respond to them. For example, it decides whether to accept connection requests, which member locators should run, exchanges membership lists with other agents and broadcasts changes in status value.

Field Summary

static int	REGISTER_NAME_CLASH Returned by register functions - member name of self is already owned by other member.
static int	REGISTER_NOT_FOUND Returned by register functions - no other member of group found within IP address range.
static int	REGISTER_OK Returned by register functions - registration successful.

Constructor Summary

Agent(Configuration configuration, MembershipList membershipList)
Constructor.

Method Summary

void	addMemberChangeListener(MemberChangeListener memberChangeListener) Adds listener to receive notification of member online and status value.
Configuration	getConfiguration() Returns configuration used by this agent.
java.lang.String	getGroupName() Returns group name of agent.
MembershipList	getMembershipList() Returns membership list used by this agent.
java.lang.String	getName() Returns name of agent, which is unique within group.
Member	getSelfMember() Returns member that represents this agent.
java.lang.String	getStatus() Returns status value of agent.
boolean	isGroupOnline() Whether at least one other member of the group is online.
boolean	isGroupRejected() Whether agent was rejected because of name clash with an existing member.
boolean	isMemberLocated(Member member) Whether member is online.
boolean	isRunning() Whether startup sequence is complete, not shutdown nor in the shutting down.
void	notifyGroupOnlineChanged() Notifies all listeners that this agent is connected or is no longer connected to at one other member of the group.
int	register(java.net.InetAddress startIPAddress, java.net.InetAddress endIPAddress, int portNo) Attempts to find an agent (of the same group) using the supplied address range and TCP port.
int	register(java.net.InetAddress iPAddress, int portNo) Attempts to find an agent (of the same group) using the supplied IP address and TCP port.
void	removeMemberChangeListener(MemberChangeListener memberChangeListener) Removes listener.
void	setStatus(java.lang.String status) Sets status value of agent and broadcasts to all other, online agents.
void	shutdown() Makes agent offline and closes all connections.
void	startup() Makes agent online, starts communications and attempts to locate other agents.

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

REGISTER_OK

public static final int REGISTER_OK

Returned by register functions - registration successful.

REGISTER_NOT_FOUND

public static final int REGISTER_NOT_FOUND

Returned by register functions - no other member of group found within IP address range.

REGISTER_NAME_CLASH

public static final int REGISTER_NAME_CLASH

Returned by register functions - member name of self is already owned by other member.

Constructor Detail

Agent

public Agent(Configuration configuration,
             MembershipList membershipList)
      throws ConfigurationException,
             java.io.IOException

Constructor. Initialises from configuration and membership list.

Parameters:

configuration - Configuration containing agent name, search limits and timeouts.

membershipList - List of known members.

Throws:

ConfigurationException - Fault with configuration object. See ConfigurationException.

java.io.IOException - Network access denied.

Method Detail

notifyGroupOnlineChanged

public void notifyGroupOnlineChanged()

Notifies all listeners that this agent is connected or is no longer connected to at one other member of the group. This also notifies that the agent was rejected because of a name clash.

getGroupName

public java.lang.String getGroupName()

Returns group name of agent.

Returns:

Group name of agent.

getName

public java.lang.String getName()

Returns name of agent, which is unique within group.

Returns:

Agent name.

getStatus

public java.lang.String getStatus()

Returns status value of agent. This has no meaning to the agent and the client is expected to interpret this value.

Returns:

Status value - cannot be null.

setStatus

public void setStatus(java.lang.String status)

Sets status value of agent and broadcasts to all other, online agents. This status value has no meaning to agents and is expected to be interpreted to clients.

Parameters:

status - Status value - cannot be null.

Throws:

java.lang.IllegalArgumentException - Status value was null.

getConfiguration

public Configuration getConfiguration()

Returns configuration used by this agent.

Returns:

Configuration used by this agent.

getMembershipList

public MembershipList getMembershipList()

Returns membership list used by this agent.

Returns:

Membership list used by this agent.

getSelfMember

public Member getSelfMember()

Returns member that represents this agent.

Returns:

Member that represents agent.

addMemberChangeListener

public void addMemberChangeListener(MemberChangeListener memberChangeListener)

Adds listener to receive notification of member online and status value.

Parameters:

memberChangeListener - Listener to add.

removeMemberChangeListener

public void removeMemberChangeListener(MemberChangeListener memberChangeListener)

Removes listener.

Parameters:

memberChangeListener - Listener to remove.

startup

public void startup()

Makes agent online, starts communications and attempts to locate other agents.

shutdown

public void shutdown()

Makes agent offline and closes all connections.

isRunning

public boolean isRunning()

Whether startup sequence is complete, not shutdown nor in the shutting down.

Returns:

True if agent has started.

register

public int register(java.net.InetAddress iPAddress,
                    int portNo)
             throws java.lang.IllegalStateException

Attempts to find an agent (of the same group) using the supplied IP address and TCP port. If successful, a known members list is sent by the remote agent and this agent is considered part of the group. This agent will attempt to connect to them later. Only attempts to connect once. Agent must be running. See REGISTER_ constants for return values.

Parameters:

iPAddress - IP address to search.

iPAddress - TCP port no to search.

Returns:

Reason code for success or failure; see REGISTER_ constants..

Throws:

java.lang.IllegalStateException - Agent is not running.

register

public int register(java.net.InetAddress startIPAddress,
                    java.net.InetAddress endIPAddress,
                    int portNo)
             throws java.lang.IllegalStateException

Attempts to find an agent (of the same group) using the supplied address range and TCP port. It is best to use as small a range as possible. If successful, a known members list is sent by the remote agent and this agent is considered part of the group. This agent will attempt to connect to them later. Only attempts to connect once. Agent must be running. See REGISTER_ constants for return values.

Parameters:

iPAddress - IP address to search.

iPAddress - TCP port no to search.

Returns:

Reason code for success or failure; see REGISTER_ constants..

Throws:

java.lang.IllegalStateException - Agent is not running.

isMemberLocated

public boolean isMemberLocated(Member member)

Whether member is online.

Returns:

True if member is online.

isGroupOnline

public boolean isGroupOnline()

Whether at least one other member of the group is online.

Returns:

True if another member of group is online.

isGroupRejected

public boolean isGroupRejected()

Whether agent was rejected because of name clash with an existing member.

Returns:

True if name clashes with existing member.