casa

Class CooperationDomain

java.lang.Object

java.lang.Thread

casa.AbstractProcess

casa.TransientAgent

casa.Agent

casa.CooperationDomain

All Implemented Interfaces:

CasaObservable, AgentInterface, AgentPrintInterface, CooperationDomainInterface, MessageSender, PolicyAgentInterface, ProcessInterface, TransientAgentInterface, TraceInterface, Comparable<AbstractProcess>, Runnable, Observer

Direct Known Subclasses:

AuctionCD

public class CooperationDomain
extends Agent
implements CooperationDomainInterface

Acts as a meeting room for other agents. It's primarily responsible for forwarding messages between agents.
In addition to the messages defined in Agent , this agent can originate the following messages types:

performative	act	see	reply handler
notify	join.cd	#notifyJoin(URLDescriptor)	-
notify	withdraw.cd	#notifyWithdraw(URLDescriptor)	-

In addition to the messages defined in Agent , this agent responds to the following messages types:

performative	act	see
request	join.cd	#respondToJoin(MLMessage)
inform	withdraw.cd	#handleWithdraw(MLMessage)
request	withdraw.cd	#respondToWithdraw(MLMessage)
request	get.members	#respondToGetMembers(MLMessage)
request	observe.membership	#respondToObserveMembership(MLMessage)
request	get.history	perform_get_history(MLMessage)
request	get.data	perform_get_data(MLMessage)
request	put.data	perform_put_data(MLMessage)

The CooperationDomain acts as a message forwarding agent and can receive messages not intended for processing by itself. The following table describes the behaviour of the CooperationDomain when it receives a message:

	"to CD" A message to this CD		"ambiguous" A message that could be to this CD		"whisper" A message to one or more CD members		"public" A broadcast message		"directed" A message to one or more CD members, but cc'ed to all
fields	rec'd message	send message	rec'd message	send message(s)	rec'd message	send message(s)	rec'd message	send message(s)	rec'd message	send message(s)
:sender	s	none	s	this-CD	s	this-CD	s	this-CD	s	this-CD
:receiver	this-CD		this-CD	forall memberi	this-CD	forall ti	this-CD	forall memberi	this-CD	forall memberi
:from	f		f	f?f:s	f	f?f:s	f	f?f:s	f	f?f:s
:to	this-CD		(empty)	*	{ti }+	ttarget {ti-ttarget}*	*	*	"+" {ti}+	"+" ttarget {ti-ttarget}*
notes	attempt to interpret and service the message		Attempt to interpret and service the message. If the CD can't, then forward it to all		t may be a list of recipients. The sent message's "to" list always has the recipient first		explicit "forward to all"		eg: Received message: ":to + url url url". Sent message: ":to the-receiver other-urls-in-the-TO-list"

In addition, this class has the following properties:

• The cooperation domain also maintains a history of all messages it forwards.
• A cooperation domain will default to being persistent if someone saves data or modifies attributes, but will not persist otherwise. However, if someone explicitly sets the cooperation domain to be non-persistent, then the cooperation domain will be non-persistent, and all data will be lost when the last member leaves.
• A cooperation domain terminates (exits) automatically when all members leave. (NOT TRUE, CURRENTLY DISABLED)
• A cooperation domain will periodically ping its members. If a member agent does not answer their pings for 3 consecutive times, they are automatically removed from membership.
• Members may send the standing request message observe.membership to the cooperation domain, and the cooperation domain will send the inform message notify.join whenever a member joins the cooperation domain and notify.withdraw whenever a member leaves the cooperation domain.

Copyright: Copyright 2003-2014, Knowledge Science Group, University of Calgary. Permission to use, copy, modify, distribute and sell this software and its documentation for any purpose is hereby granted without fee, provided that the above copyright notice appear in all copies and that both that copyright notice and this permission notice appear in supporting documentation. The Knowledge Science Group makes no representations about the suitability of this software for any purpose. It is provided "as is" without express or implied warranty.

Version:

0.9

Author:

Rob Kremer, Jason Heard, Vladimir Sedach, Daniel Bidulock

Nested Class Summary

Nested classes/interfaces inherited from class casa.TransientAgent

TransientAgent.Conversations, TransientAgent.NewAgentLispCommand

Nested classes/interfaces inherited from class casa.AbstractProcess

AbstractProcess.Subthread

Nested classes/interfaces inherited from class java.lang.Thread

Thread.State, Thread.UncaughtExceptionHandler

Field Summary

Fields

Modifier and Type	Field and Description
protected static String	HISTORY_NODE The name of the data object in which we store the cooperation domain message history.
protected Vector<URLDescriptor>	members A Vector of URLDescriptors of the members of this cooperation domain.
protected Hashtable<URLDescriptor,String>	membershipSubscriptions
private Hashtable<URLDescriptor,String>	messageObservers The mesage notification list.
static int	PING_CHANCES The number of times a member agent's ping must timeout before it is withdrawn from this cooperation domain.
private static long	PING_INTERVAL The interval that determines how often this agent will attempt to ping its members.
private static long	PING_WAIT_TIME The ping timeout value used when this agent's members are pinged.
private RecurringTimeEvent	pingMemebersEvent
private long	pingTime The next moment in time that all of our members will be pinged.

Fields inherited from class casa.Agent

agentConstructorComplete, properties

Fields inherited from class casa.TransientAgent

cacheKB, CDInvitedTo, CDinvitee, conversationData, defaultOntologyClassName, DEFER_ACTION, DROP_ACTION, kBase, lisp, lispEnvironment, ListOfArgs, methodMap, ontologyEngine, ontologyEngineCreateMethod, ontologyEngineLoadMethod, policies, policiesAlwaysApply, policiesLastResort, primaryUI, proxy, UIs, usingProxy

Fields inherited from class casa.AbstractProcess

eventQueue, exitWaitCounter, heartbeat, huntForPort, initParams, ontology, ontologyShared, options, securityFilter, trace, TRACE_MONITOR, TRACE_OFF, TRACE_ON, TRACE_TO_FILE, TRACE_UNDEFINED, transformations, uniqueThreadName, waitingForAgentToStart, waitingForEvent, waitingForSocketServerToStart

Fields inherited from class java.lang.Thread

MAX_PRIORITY, MIN_PRIORITY, NORM_PRIORITY

Constructor Summary

Constructors

Constructor and Description
CooperationDomain(ParamsMap params, AgentUI ui) Creates a new CooperationDomain.

Method Summary

Modifier and Type	Method and Description
protected void	archiveMessage(MLMessage message) Stores the given message in this cooperation domain's history node.
protected PerformDescriptor	assembleDefault(MLMessage message) The default code for dealing with a proxy message.
protected PerformDescriptor	conclude_membership_change(MLMessage message)
PerformDescriptor	consider_proxy_message(MLMessage message) Public method for forwarding proxy messages (I think)
static MLMessage	constructCDProxyMessage(MLMessage message, URLDescriptor sender, URLDescriptor cd) Constructs a new proxy message which instructs the cooperation domain to forward the encapsulated message to all current members of that cooperation domain.
static MLMessage	constructCDProxyMessage(MLMessage message, URLDescriptor sender, URLDescriptor cd, List<URLDescriptor> to, boolean whisper) Constructs a new proxy message which instructs the cooperation domain to forward the encapsulated directed or whisper message.
static MLMessage	constructCDProxyMessage(MLMessage message, URLDescriptor sender, URLDescriptor cd, URLDescriptor to, boolean whisper) Constructs a new proxy message which instructs the cooperation domain to forward the encapsulated directed or whisper message.
PerformDescriptor	evaluate_membership_change(MLMessage message)
Pair<List<URLDescriptor>,MLMessage>	extractCDProxyInformation(String content) Using the content parameter, parse out the members to forward a message to.
protected void	finishRun() Subclasses may override this method to cleanup after the message loop exits and the agent is about to terminate.
String	getCDCreator() Retreives the creator (username) of the cooperation domain.
StatusMLMessageList	getEntireHistory() Retreives the entire history for the cooperation domain.
StatusMLMessageList	getHistory(URLDescriptor member) Retreives the history for a given agent in the cooperation domain.
Vector<URLDescriptor>	getMembers() Retreives a membership list for the cooperation domain.
void	initializeAfterRegistered(boolean registered) Called by handleReply_registerAgentInstance.
Status	join(URLDescriptor joiner) Adds the specified agent to the list of current members and notifies any agents that are observing membership that a new member has joined the cooperation domain.
protected TransientAgentInternalFrame	makeDefaultInternalFrame(TransientAgent agent, String title, Container aFrame) Create the default internal Frame (usually) with tabs for this agent type.
protected void	notifySendingMessage(MLMessage message) This method is to be overridden by any subclasses that wish to be informed whenever a message is actually sent out.
Status	observeMessages(URLDescriptor agent, String replyWith, boolean addIfTrue) Adds or removes the given agent to/from the message notification list.
protected void	pendingFinishRun() Override of method to cleanup after an #AbstractProcess.exit() has been called, but before the message loop exits and the agent is about to terminate.
protected PerformDescriptor	perform_get_data(MLMessage message) Responds to an incoming get.data request message by sending a reply giving the status of the operation and the requested data.
protected PerformDescriptor	perform_get_history(MLMessage message) Responds to a get.history request using getHistory(URLDescriptor) to reply.
PerformDescriptor	perform_get_members(MLMessage message)
PerformDescriptor	perform_join_cd(MLMessage message) Responds to a join.cd request.
protected PerformDescriptor	perform_observe_messages(MLMessage message) Deprecated.
protected PerformDescriptor	perform_put_data(MLMessage message) Responds to an incoming put.data request message by sending a reply giving the status of the operation.
PerformDescriptor	perform_withdraw_cd(MLMessage message) Responds to a withdraw.cd request.
protected PerformDescriptor	release_membership_change(MLMessage message)
PerformDescriptor	release_ping(MLMessage msg) This method is called when a ping reply message is received in response to a previously sent ping request message.
private Status	sendForwardedMessage(MLMessage message) Deprecated.
private void	setCDCreator(String cdCreator) Sets the creator (username) of the cooperation domain to the given value.
Status	withdraw(URLDescriptor member) Removes the specified agent from the list of current members and notifies any agents that are observing membership that a member has withdrawn from the cooperation domain.

Methods inherited from class casa.Agent

destroyDataObject, finalize, getAgentOptions, getBooleanProperty, getCASAFilename, getCreateDate, getDataObject, getDataObjectInputStream, getDataObjectOutputStream, getDoubleProperty, getFloatProperty, getIntegerProperty, getLongProperty, getOptions, getStringProperty, hasProperty, isPersistent, main, makeDefaultGUI, makeOptions, putDataObject, putDataObject, readPersistent, ready, realizeAgentBehaviourFromOptions, removeProperty, setBooleanProperty, setDoubleProperty, setFloatProperty, setIntegerProperty, setLongProperty, setOptions, setPersistent, setStringProperty, updateOptions, writePersistent

Methods inherited from class casa.TransientAgent

abclEval, abclEval, abclEval, accept_deleteCD, accept_exit, accept_forward_message, accept_LAC_closing, accept_new_MenuItem, accept_update, acceptDefault, addConversation, addJoinedCooperationDomain, addMembers, addSubscribeEvents, assert_, assert_, authorizedByProxy, authorizeMessage, chooseSC, concludeDefault, consider_execute, consider_invite_to_cd, consider_new_MenuItem, consider_ping, consider_query_if, consider_query_ref, considerDefault, createCasaLispOperators, dispatchMsgHandlerMethod, doAddObserver, doAdvertise, doCDGetHistory_sync, doCDGetMembers, doCDPutData, doCDSubscribeMembership, doFindInstances_sync, doGetCooperationDomains, doGetOnology, doInviteToCD, doJoinCD, doPing_sync, doPing, doRegisterAgentInstance, doRegisterAgentInstance, doResolveURL, doSearchYP, doUnadvertise, doUnregisterAgentInstance, doUnregisterAgentType, doWithdrawCD, evaluateDefault, evesdrop, executeCommand, findFileResourcePath, findFileResourcePath, getAgentForThread, getAlwaysApplyPolicies, getBanner, getCachedKnowledgeBase, getChosenCommitment, getCommitmentProcessor, getConversation, getConversations, getConversationsReport, getDefaultBanner, getDefFileSystemLocations, getEventForThread, getField, getInstancesFound, getJoinedCooperationDomain, getJoinedCooperationDomains, getKnowledgeBase, getLACURL, getLastResortPolicies, getMembers, getMsgForThread, getObjectsForThread, getOntology, getOntologyEngine, getOntologyFileSuffix, getPolicies, getPrimaryUI, getProxy, getSCStore, getSerializedOntology, getStrategy, getStrategyGUI, getSubscribeEvents, getSubscribeEvents, getTermsFromContent, getUI, getUIForThread, getUIs, getUnfulfilledSocialCommitments, getUnfulfilledSocialCommitments, handleErrorReplies, handleEvent, handleLACClosing, hasActiveCommitments, hasConversation, hasStrategyGUI, initializePolicies, initializeThread, initJADE, initUI, isEventQueueReady, isRegistered, isRegisteredWithLAC, isStoppable, isTrusted, isTrusted, isUsingProxy, kb_get_value, makeDefaultInterface, makeDefaultTextInterface, monitorDefault, optionsToString, parseJADENode, pendingFinishRun_unregisterAgentInstance, pendingFinishRun_withdrawFromAllCDs, perform_execute, perform_FIPAStyle, perform_get_name, perform_get_ontology, perform_invite_to_cd, perform_method_call, perform_query_if, perform_query_if, perform_query_ref, perform_query_ref, performDefault, processCommitment, processCommitments, processObserverNotification, putExtendedOntology, putPolicy, putPolicyAlwaysApply, putPolicyLastResort, putReplacementOntology, putUI, query_ref, query_toString, query, queryIf, queryRef_toIntegerList, queryRef_toString, queryRef_toStringList, queryRef_toTermList, queryRef, queryRef, queryRefAIDs, queryRefURLs, querywithFilter, recursiveParent, recursivePermutations, release_execute, release_FIPAStyle, release_get_agents_registered, release_get_agents_running, release_get_members, release_get_ontology, release_join_cd, release_query_if, release_query_ref, release_resolve_url, release_unregister_agentType, release_unregister_instance, release_withdraw_cd, releaseDefault, removeConversation, removeCooperationDomains, removeJoinedCooperationDomain, removeSubscribeEvents, requestInstances, resolveConnectException, retrieveReturnedData, saveReturnedData, searchOntology, searchOntology1, setBanner, setCommitmentProcessor, setField, setInstancesFound, setOntology, shouldDoExecuteRequest, template_handleNewOntologyInfo, update, updateConversationProtocolType, verifyCD, verifyDefault, verifyMessage

Methods inherited from class casa.AbstractProcess

addObserver, addObserver, addObserver, addObserver, addTraceTags, addTransformation, bump, clearAllTraceTags, closePort, compareTo, countObservers, defer, defer, deleteObserver, deleteObserver, deleteObservers, dequeueEvent, equals, eventBufferLoopBody, eventBufferLoopPeriodic, eventQueuePeek, existed, exit, fixupMessage, getAgent, getAgentName, getEventQueue, getInitParams, getNewMessage, getNewMessage, getPort, getSocketServer, getTrace, getTraceTags, getTransformationFor, getUniqueRequestID, getURL, getUseAckProtocol, getUsePriority, hasChanged, hasOpenPort, in, initializeConstructor, initializeURL, isA, isA, isA, isA, isAAct, isAAct, isAgentThread, isAPerformative, isAPerformative, isExiting, isInitialized, isLoggingTag, isObserveMessages, isPaused, isThisMyAddress, isTracing, loadClass, makeSubthread, makeSubthread, makeTraceParam, notifyObservers, notifyObservers, notifyObserversWithNoArg, notifyObserversWithTop, out, println, println, println, println, println, queueEvent, queueEventIf, removeTraceTags, resetRuntimeOptionsFromCommandLine, resetSecurityPackage, resetTraceOptions, revTransform, revTransform, run, sendMessage_primitive, sendMessage, sendMessage, sendMessageAndWait, sendQueryAndWait, sendRequestAndWait, sendRequestAndWait, setAllTraceTags, setObserveMessages, setPause, setTraceTags, setTracing, setURL, setUseAckProtocol, setUsePriority, startSocketServer, startTraceMonitor, step, transform, transform, unhandledMessage

Methods inherited from class java.lang.Thread

activeCount, checkAccess, clone, countStackFrames, currentThread, destroy, dumpStack, enumerate, getAllStackTraces, getContextClassLoader, getDefaultUncaughtExceptionHandler, getId, getName, getPriority, getStackTrace, getState, getThreadGroup, getUncaughtExceptionHandler, holdsLock, interrupt, interrupted, isAlive, isDaemon, isInterrupted, join, join, join, resume, setContextClassLoader, setDaemon, setDefaultUncaughtExceptionHandler, setName, setPriority, setUncaughtExceptionHandler, sleep, sleep, start, stop, stop, suspend, toString, yield

Methods inherited from class java.lang.Object

getClass, hashCode, notify, notifyAll, wait, wait, wait

Methods inherited from interface casa.interfaces.AgentInterface

destroyDataObject, getBooleanProperty, getCASAFilename, getDataObject, getDataObjectInputStream, getDataObjectOutputStream, getDoubleProperty, getFloatProperty, getIntegerProperty, getLongProperty, getStringProperty, hasProperty, isPersistent, putDataObject, putDataObject, ready, removeProperty, setBooleanProperty, setDoubleProperty, setFloatProperty, setIntegerProperty, setLongProperty, setPersistent, setStringProperty

Methods inherited from interface casa.interfaces.TransientAgentInterface

doAdvertise, doCDGetHistory_sync, doCDGetMembers, doCDPutData, doFindInstances_sync, doGetCooperationDomains, doGetOnology, doInviteToCD, doJoinCD, doPing_sync, doPing, doRegisterAgentInstance, doRegisterAgentInstance, doSearchYP, doUnadvertise, doUnregisterAgentInstance, doUnregisterAgentType, doWithdrawCD, executeCommand, getInstancesFound, getJoinedCooperationDomains, getLACURL, getMembers, getOntology, getOptions, getSerializedOntology, getStrategyGUI, hasStrategyGUI, isAAct, isInitialized, isRegistered, makeDefaultInterface, putExtendedOntology, putReplacementOntology, putUI, release_get_ontology, removeCooperationDomains, requestInstances, setOptions, updateOptions

Methods inherited from interface casa.interfaces.ProcessInterface

addObserver, addObserver, closePort, deleteObserver, deleteObserver, exit, getAgentName, getName, getNewMessage, getPort, getStrategy, getTrace, getUniqueRequestID, getURL, getUseAckProtocol, hasOpenPort, isA, isAPerformative, isExiting, isLoggingTag, isStoppable, isTracing, println, println, println, realizeAgentBehaviourFromOptions, sendMessage, setTracing, setUseAckProtocol, startTraceMonitor

Methods inherited from interface java.lang.Runnable

run

Methods inherited from interface casa.CasaObservable

addObserver, addObserver, countObservers, deleteObservers, hasChanged, notifyObservers, notifyObservers, notifyObserversWithNoArg, notifyObserversWithTop

Methods inherited from interface casa.interfaces.PolicyAgentInterface

abclEval, abclEval, abclEval, addTransformation, bump, chooseSC, defer, dequeueEvent, dispatchMsgHandlerMethod, evesdrop, getKnowledgeBase, getName, getSCStore, getSubscribeEvents, getTransformationFor, getUniqueRequestID, getURL, getUseAckProtocol, isA, isA, isA, isA, isAPerformative, isAPerformative, isLoggingTag, notifyObservers, println, println, println, queueEvent, queueEventIf, revTransform, revTransform, sendMessage, transform, transform

Methods inherited from interface java.util.Observer

update

Field Detail

HISTORY_NODE

protected static String HISTORY_NODE

The name of the data object in which we store the cooperation domain message history.

members

protected Vector<URLDescriptor> members

A Vector of URLDescriptors of the members of this cooperation domain.

membershipSubscriptions

protected Hashtable<URLDescriptor,String> membershipSubscriptions

messageObservers

private Hashtable<URLDescriptor,String> messageObservers

The mesage notification list. A Hashtable linking the URLDescriptor of an agent that is observing the messages of this cooperation domain to a String of the ML.REPLY_WITH parameter that should be used when notifying that agent of sent messages.

pingMemebersEvent

private RecurringTimeEvent pingMemebersEvent

PING_INTERVAL

private static final long PING_INTERVAL

The interval that determines how often this agent will attempt to ping its members.

See Also:

messageBufferLoopPeriodic(), Constant Field Values

PING_WAIT_TIME

private static final long PING_WAIT_TIME

The ping timeout value used when this agent's members are pinged.

See Also:

messageBufferLoopPeriodic(), Constant Field Values

PING_CHANCES

public static final int PING_CHANCES

The number of times a member agent's ping must timeout before it is withdrawn from this cooperation domain. This is public because it is also used by CooperationDomainListModel for fading visual effects.

See Also:

messageBufferLoopPeriodic(), Constant Field Values

pingTime

private long pingTime

The next moment in time that all of our members will be pinged. This is initially set to the current time plus PING_INTERVAL.

See Also:

messageBufferLoopPeriodic()

Constructor Detail

CooperationDomain

public CooperationDomain(ParamsMap params,
                         AgentUI ui)
                  throws Exception

Creates a new CooperationDomain.

Parameters:

params -

ui -

Throws:

Exception - If the agent creation fails for any reason.

Method Detail

finishRun

protected void finishRun()

Description copied from class: AbstractProcess

Subclasses may override this method to cleanup after the message loop exits and the agent is about to terminate. Called once, just before the agent terminates. This implementation does nothing but call notifyObservers(state.STATE_EXITED).

Overrides:

finishRun in class AbstractProcess

initializeAfterRegistered

public void initializeAfterRegistered(boolean registered)

Description copied from class: Agent

Called by handleReply_registerAgentInstance. During the constructor, the Agent registers with the LAC, but has to wait for the LAC to reply before initializing the file and properties. This init() method is called at that time to initialize the file and properties.
This version handles persistence details, and calls the super method (TransientAgent.initializeAfterRegistered(boolean)) after processing the persistent data.

Overrides:

initializeAfterRegistered in class Agent

Parameters:

registered - Will be set to true if the agent has sucessfully registered with the LAC; false otherwise

See Also:

TransientAgent.initializeAfterRegistered(boolean)

setCDCreator

private void setCDCreator(String cdCreator)

Sets the creator (username) of the cooperation domain to the given value. This allows the security system (in this case the authorization) to retrieve the user that has "unlimited" access to the cooperation domain. Returns a String value representing the username of the creator of the cooperation domain. This person/agent has full access rights in the cooperation domain. This means that this person/agent can modify other users' access rights. That is, limit or upgrade the level of cooperation and collaboration that a person/agent has in the specific cooperation domain.

Parameters:

cdCreator - A String value representing the username of the creator of the cooperation domain.

assembleDefault

protected PerformDescriptor assembleDefault(MLMessage message)

Description copied from class: TransientAgent

The default code for dealing with a proxy message. Subclasses may override this method to change the default behavior. In this case, it just returns a StatusObject, MLMessage>> object (limited to one element), which indicates that the message will be forwarded to one agent only.

Overrides:

assembleDefault in class TransientAgent

Parameters:

message - the message that precipitated this action

Returns:

null always

extractCDProxyInformation

public Pair<List<URLDescriptor>,MLMessage> extractCDProxyInformation(String content)

Using the content parameter, parse out the members to forward a message to. The content parameter should contain a serialized vector of the address string and a message to forward. The address string is of 3 possible syntaxes:

1. "*" - broadcast
2. "+" { url }* - directed (addressed, but public broadcast)
3. { url }* - whisper (private)

No non-members (as specified by the members parameter) are ever included in the the returned members-to-forward list, which will contain all the members in case 1 and 2, but only the targeted agents in case 3. The returned message will be the same as the message in the content but will have a new RECIPIENTS field containing the intented recipients in case 2 and 3, or "*" in case 1. Note that the RECIPIENTS field is NOT the same as the returns list of urls.
If, after all this, there are no list or urls to return, an error message is displayed.

Parameters:

content -

Returns:

constructCDProxyMessage

public static MLMessage constructCDProxyMessage(MLMessage message,
                                                URLDescriptor sender,
                                                URLDescriptor cd,
                                                URLDescriptor to,
                                                boolean whisper)

Constructs a new proxy message which instructs the cooperation domain to forward the encapsulated directed or whisper message. A whisper message is forwarded only to the given agent, while a directed message is forwarded to all agents, but marked as directed towards the given agent.

Parameters:

message - The message to encapsulate within the proxy message.

sender - The sender of the proxy message.

cd - The cooperation domain which will recieve the proxy message and forward the encapsulated message.

to - A List containing the URLDescriptors of the agents that should recieve the encapsulated message.

whisper - Constructs a whisper message if true; constructs a directed message if false.

Returns:

A new proxy message.

See Also:

MLMessage.constructProxyMessage(MLMessage, URLDescriptor, URLDescriptor, String)

constructCDProxyMessage

public static MLMessage constructCDProxyMessage(MLMessage message,
                                                URLDescriptor sender,
                                                URLDescriptor cd,
                                                List<URLDescriptor> to,
                                                boolean whisper)

Constructs a new proxy message which instructs the cooperation domain to forward the encapsulated directed or whisper message. A whisper message is forwarded only to the given agents, while a directed message is forwarded to all agents, but marked as directed towards the given agents.

Parameters:

message - The message to encapsulate within the proxy message.

sender - The sender of the proxy message.

cd - The cooperation domain which will recieve the proxy message and forward the encapsulated message.

to - A List containing the URLDescriptors of the agents that should recieve the encapsulated message.

whisper - Constructs a whisper message if true; constructs a directed message if false.

Returns:

A new proxy message.

See Also:

MLMessage.constructProxyMessage(MLMessage, URLDescriptor, URLDescriptor, String)

constructCDProxyMessage

public static MLMessage constructCDProxyMessage(MLMessage message,
                                                URLDescriptor sender,
                                                URLDescriptor cd)

Constructs a new proxy message which instructs the cooperation domain to forward the encapsulated message to all current members of that cooperation domain.

Parameters:

message - The message to encapsulate within the proxy message.

sender - The sender of the proxy message.

cd - The cooperation domain which will recieve the proxy message and forward the encapsulated message.

Returns:

A new proxy message.

See Also:

MLMessage.constructProxyMessage(MLMessage, URLDescriptor, URLDescriptor, String)

sendForwardedMessage

@Deprecated
private Status sendForwardedMessage(MLMessage message)

Deprecated.

Take care of forwarding messages. This would be straight forward, except that we also need to construct and send INFORM/MESSAGE/FORWARDED messages to any observers we might have. TODO Finish documenting the sendForwardedMessage method.

Deprecated in favour of consider_proxy_message(MLMessage)

Parameters:

message - the message to forward

Returns:

the status returned from a call to AbstractProcess.sendMessage(MLMessage)

See Also:

consider_proxy_message(MLMessage)

notifySendingMessage

protected void notifySendingMessage(MLMessage message)

Description copied from class: TransientAgent

This method is to be overridden by any subclasses that wish to be informed whenever a message is actually sent out.

Overrides:

notifySendingMessage in class TransientAgent

archiveMessage

protected void archiveMessage(MLMessage message)

Stores the given message in this cooperation domain's history node.

Parameters:

message - The message to store in the hostory node.

consider_proxy_message

public PerformDescriptor consider_proxy_message(MLMessage message)

Public method for forwarding proxy messages (I think)

Parameters:

message -

Returns:

the PerformDescriptor containing the Status of the CooperationDomain#sendForwardMessage(MLMessage) call

perform_join_cd

public PerformDescriptor perform_join_cd(MLMessage message)

Responds to a join.cd request. The format of the incoming message is:

performative	request
act	join.cd
language	casa.agentCom.URLDescriptor
content	a URLDescriptor object for the agent that wants to join

and responds with:

	success or warning	failure
performative	reply	failure | refuse
act	join.cd	join.cd
language	casa.Status	casa.Status
content	a Status object	a Status object

The failuremessage is sent if the message is malformed; the refuse message is sent if join(URLDescriptor) returned a negative Status (the requester agent was not joined to the domain).

Parameters:

message - an incoming join.cd request message

Returns:

the status of the AbstractProcess.sendMessage(MLMessage) call for the reply message

join

public Status join(URLDescriptor joiner)

Adds the specified agent to the list of current members and notifies any agents that are observing membership that a new member has joined the cooperation domain.

Specified by:

join in interface CooperationDomainInterface

Parameters:

joiner - The agent who is joining the cooperation domain.

Returns:

The Status of the join:

0 if it was successful with no warnings or errors, or

1 if the agent was already a member and its URL is updated in the member list.

perform_withdraw_cd

public PerformDescriptor perform_withdraw_cd(MLMessage message)

Responds to a withdraw.cd request. The format of the incoming message is:

performative	request
act	withdraw.cd
language	casa.agentCom.URLDescriptor
content	a URLDescriptor object for the agent that wants to withdraw

and responds with:

	success or warning	failure
performative	reply	failure | refuse
act	join.cd	join.cd
language	casa.Status	casa.Status
content	a Status object	a Status object

The failuremessage is sent if the message is malformed; the refuse message is sent if withdraw(URLDescriptor) returned a negative Status (the requester agent was not joined to the domain).

Parameters:

message - an incoming withdraw.cd request message

Returns:

the status of the AbstractProcess.sendMessage(MLMessage) call for the reply message

pendingFinishRun

protected void pendingFinishRun()

Override of method to cleanup after an #AbstractProcess.exit() has been called, but before the message loop exits and the agent is about to terminate.

Overrides:

pendingFinishRun in class Agent

See Also:

AbstractProcess.pendingFinishRun()

withdraw

public Status withdraw(URLDescriptor member)

Removes the specified agent from the list of current members and notifies any agents that are observing membership that a member has withdrawn from the cooperation domain.

Specified by:

withdraw in interface CooperationDomainInterface

Parameters:

member - The agent (presumably a member) who is withdrawing from the cooperation domain.

Returns:

The Status of the withdrawl:

0 if it was successful with no warnings or errors, or

1 if the agent was not already a member.

perform_get_members

public PerformDescriptor perform_get_members(MLMessage message)

getMembers

public Vector<URLDescriptor> getMembers()

Retreives a membership list for the cooperation domain. Returns a Vector of URLDescriptors that are members of the cooperation domain.

Specified by:

getMembers in interface CooperationDomainInterface

Returns:

A Vector of URLDescriptors (encapsulated in a StatusURLDescriptorList) that are members of the cooperation domain. The status will be:

0 indicating the operation was successful.

evaluate_membership_change

public PerformDescriptor evaluate_membership_change(MLMessage message)

release_membership_change

protected PerformDescriptor release_membership_change(MLMessage message)

conclude_membership_change

protected PerformDescriptor conclude_membership_change(MLMessage message)

perform_observe_messages

@Deprecated
protected PerformDescriptor perform_observe_messages(MLMessage message)

Deprecated.

Responds to a observe.messages subscribe message by setting up (or cancelling) notify messages whenever a message is sent within the cooperation domain. The handled messages are of the format:

performative	subscribe
act	observe.messages
reply-by	0
sense	positive | negative
language	casa.agentCom.URLDescriptor
content	a URLDescriptor object

The nofify messages will be of the format:

performative	notify
act	message.forwarded
language	casa.agentCom.URLDescriptor
content	a URLDescriptor object

Parameters:

message - an incoming observe.membership subscribe message

Returns:

a Status object with a value of 0

observeMessages

public Status observeMessages(URLDescriptor agent,
                              String replyWith,
                              boolean addIfTrue)

Adds or removes the given agent to/from the message notification list.

Parameters:

agent - The agent (presumably not a member) who is requesting to be added or removed from the list of agents that would like to be notified of every message forwarded by the cooperation domain.

replyWith - This is the REPLY_WITH parameter of the original request that should be used in all of the notifications in reply to that message. This may be null if addIfTrue is false.

addIfTrue - This should be true if the agent is would like to be added to the list; false otherwise.

Returns:

The Status of the operation:

0 if it was successful with no warnings or errors, or

1 if the agent was not already a member.

perform_get_history

protected PerformDescriptor perform_get_history(MLMessage message)

Responds to a get.history request using getHistory(URLDescriptor) to reply. It handles request messages of the form:

performative	request
act	get.history

It replies with a message of the format:

	success or warning	failure
performative	reply	failure
act	get.history	get.history
language	casa.StatusMLMessageList	text
content	a StatusMLMessageList object	explanitory text

Parameters:

message - the incoming get.history request message

Returns:

the Status of the sendMessage used to send the reply or a Status of value -1 if the sendMessage thows and exception.

getHistory

public StatusMLMessageList getHistory(URLDescriptor member)

Retreives the history for a given agent in the cooperation domain. Returns a list of MLMessages (encapsulated in a StatusMLMessageList) that have been sent within the cooperation domain to the given agent or to all agents.

Specified by:

getHistory in interface CooperationDomainInterface

Parameters:

member - The member for whom we are retreiving the history.

Returns:

A Vector of MLMessages (encapsulated in a StatusMLMessageList) that have been sent within the cooperation domain to the given agent or to all agents. The status will be:

0 if the operation was successful, or

1 if there were errors loading the history, or parsing the messages.

getEntireHistory

public StatusMLMessageList getEntireHistory()

Retreives the entire history for the cooperation domain. Returns a list of MLMessages (encapsulated in a StatusMLMessageList) that have been sent within the cooperation domain.

Specified by:

getEntireHistory in interface CooperationDomainInterface

Returns:

A Vector of MLMessages (encapsulated in a StatusMLMessageList) that have been sent within the cooperation domain. The status will be:

0 if the operation was successful, or

1 if there were errors loading the history.

perform_put_data

protected PerformDescriptor perform_put_data(MLMessage message)

Responds to an incoming put.data request message by sending a reply giving the status of the operation. The handled message if of the form:

performative	request
act	put.data
language	casa.DataStorageDescriptor
content	a DataStorageDescriptor object

The reply message is of the form:

	success or warning	failure
performative	reply	failure | refuse
act	put.data	put.data
language	casa.Status	casa.Status
content	a Status object	a Status object

The failuremessage is sent if the message is malformed; the refuse message is sent if the agent is trying to write to a reserved data node.

Parameters:

message - an incoming put.data request message

Returns:

the status of the AbstractProcess.sendMessage(MLMessage) call for the reply message

perform_get_data

protected PerformDescriptor perform_get_data(MLMessage message)

Responds to an incoming get.data request message by sending a reply giving the status of the operation and the requested data. The handled message if of the form:

performative	request
act	get.data
language	identifier
content	named-data name

It sends a mesage of the format:

	success or warning	failure
performative	reply	failure
act	get.data	get.data
language	casa.StatusString	casa.Status
content	a StatusString object	a Status object

The failuremessage is sent if the message is malformed.

Parameters:

message - an incoming get.data request message

Returns:

the status of the AbstractProcess.sendMessage(MLMessage) call for the reply message

release_ping

public PerformDescriptor release_ping(MLMessage msg)

This method is called when a ping reply message is received in response to a previously sent ping request message. We override this method to clear the respoinder's marks (if the ping'ee doesn't respond so many times in a row, it will be removed from the list of members.

Overrides:

release_ping in class TransientAgent

Parameters:

msg - the incomming reply message

Returns:

a Status object as described above. 0 if the message was not an error or malformed, or a negative Status according to TransientAgent.verifyMessage(MLMessage,String[])

getCDCreator

public String getCDCreator()

Retreives the creator (username) of the cooperation domain. This allows the security system (in this case the authorization) to retrieve the user that has "unlimited" access to the cooperation domain. Returns a String value representing the username of the creator of the cooperation domain. This person/agent has full access rights in the cooperation domain. This means that this person/agent can modify other users' access rights. That is, limit or upgrade the level of cooperation and collaboration that a person/agent has in the specific cooperation domain.

makeDefaultInternalFrame

protected TransientAgentInternalFrame makeDefaultInternalFrame(TransientAgent agent,
                                                               String title,
                                                               Container aFrame)

Create the default internal Frame (usually) with tabs for this agent type.

Overrides:

makeDefaultInternalFrame in class Agent

Parameters:

agent - the owner agent

title - the title of the window

aFrame - the owner frame in which this window is to be embedded

Returns:

the frame