% PARTOF texte:da/tex/a_home.tex
\begin{xple}
\begin{tabbing}
\hspace*{0.7cm}\=\hspace{0.5cm}\=\hspace{0.5cm}\=\hspace{0.5cm}\=\hspace{0.5cm}\=
\hspace{0.5cm}\=\hspace{0.5cm}\=\hspace{0.5cm}\=\hspace{0.5cm}\=\hspace{0.5cm}
\=\hspace{0.5cm}\=\kill
{\em interface} Agent                                                                     \\
{\em import} location \ tbConv \ tbcSpec \ wwuid                                                  \\
{\em export}                                                                              \\
\>error :{\em Exception} reason :String {\em end}                                               \\
\>(* Raised if an operation failes *)                                               \\
\>meetingDenied :{\em Exception}\ {\em end}                                                     \\
\>(* Raised from an agent if it is not interested in a meeting an other             \\
\>\> agent asked for. *)                                                          \\
\>deferedDialog() :tbConv.Dialog                                                    \\
\>(* This special dialog may be returned by a performer rule instead of             \\
\>\> the dialog which is expected w.r.t the current conversation specification.     \\
\>\> It is intercepted by the agent and will not be delivered                      \\
\>\> to the conversations customer agent. The reply is defered until a              \\
\>\> customer rule calls conversation.reply() for this conversation. *)           \\
\>(* === Abstract (migration-safe) agent handle: *)                                 \\
\>{\em Let} T = {\em Tuple}                                                                     \\
\>\>name :String (* The high-level name of an agent *)                       \\
\>\>id :wwuid.T  (* It's world-wide unique identificator *)                  \\
\>\>owner :wwuid.T (* The owners id of an agent *)                             \\
\>\>home :location.T (* The agents home location *)                              \\
\>{\em end}                                                                               \\
\>equal(a1,a2 :T) :Bool                                                             \\
\>(* Check if the agent handles a1 and a2 denote the same agents. *)                \\
\>(* === Agent types: *)                                                            \\
\>new(A $<$:{\em Ok} \ a :A                                                                  \\
\>\>\>birth(self :T \ a :A) :{\em Ok}                                                      \\
\>\>\>\> (* Executed after agent is created successfully in its place. *)           \\
\>\>\>meet(self,other :T \ spec :tbcSpec.T \ a :A) :T                                 \\
\>\>\>\> (* Executed if some agent wants to meet this agent. *)                     \\
\>\>\>die(self :T \ a :A) :{\em Ok}                                                        \\
\>\>\>\> (* Finalizer. Executed if the agent is shut up. *)                         \\
\>\>\>leave(self,fromPlace :T \ a :A) :{\em Ok}                                            \\
\>\>\>\>(* Executed if the domain is ready to ship the agent to                    \\
\>\>\>\>\>another place. (niy) *)                                                 \\
\>\>\>enter(self,atPlace :T \ a :A) :{\em Ok}                                              \\
\>\>\>\> (* Executed if the domain has shipped this agent to                        \\
\>\>\>\>\>another place. (niy) *)                                                 \\
\>\>\>owner :T \ name :String) :T                                                    \\
\>(* Create a new mobile agent. *)                                  \\
\>newPlace(A $<$:{\em Ok} \ a :A                                                             \\
\>\>\> birth(self :T \ a :A) :{\em Ok}                                                     \\
\>\>\>\> (* Executed after agent is created successfully in its place. *)           \\
\>\>\> meet(self,other :T \ spec :tbcSpec.T \ a :A) :T                                \\
\>\>\>\> (* Executed if some agent wants to meet this agent. *)                     \\
\>\>\> die(self :T \ a :A) :{\em Ok}                                                       \\
\>\>\>\> (* Finalizer. Executed if the agent is shut up. *)                         \\
\>\>\> incomingAgent(self,other :T \ a :A) :Bool                                     \\
\>\>\>\> (* Executed if the domain is about to ship an agent into this              \\
\>\>\>\>\>place. Will also be executed if an agent is to be created               \\
\>\>\>\>\>in this place. *)                                                       \\
\>\>\> outgoingAgent(self,other :T \ a :A) :{\em Ok}                                       \\
\>\>\>\> (* Executed if the domain is about to ship an agent from this              \\
\>\>\>\>\>place. *)                                                               \\
\>\>\> owner :T \ name :String) :T                                                   \\
\>(* Create a new place.  *)                 \\
\>(* === Agent roles: *)                                                            \\
\>{\em Let} {\em Rec} Conversation(S $<$:{\em Ok}) $<$:{\em Ok} = {\em Tuple}                                         \\
\>\>c :tbConv.T(S)                                                                  \\
\>\>(* A conversation handle. *)                                                    \\
\>\>peer :T                                                                         \\
\>\>(* The conversation partner. *)                                                 \\
\>\>reply(S $<$:{\em Ok} \ performerConversation :Conversation(S)                            \\
\>\>\>\>dialog :tbConv.Dialog) :{\em Ok}                                                \\
\>\>(* Sends the dialog in the given performerConversation to the bound             \\
\>\>\> customer (see deferedDialog()).*)                                            \\
\>{\em end}                                                                               \\
\>(* A Conversation representation with a local state of type S. *)                 \\
\>{\em Let} RequestName = String                                                          \\
\>{\em Let} CustomerRole(S $<$:{\em Ok}) $<$:{\em Ok} = {\em Tuple}                                             \\
\>\>spec() :tbcSpec.T                                                               \\
\>\>(* The bound specification for this role. *)                                    \\
\>\>isNil() :Bool                                                                   \\
\>\>(* Returns true iff role is a nil role. *)                                      \\
\>\>set(dialogName :String \ action(:Conversation(S)) :RequestName) :{\em Ok}              \\
\>\>(* Action will be executed atomically whenever a performer returns a            \\
\>\>\> dialog with this dialogName. *)                                              \\
\>\>startConversation(performer :T \ s :S) :{\em Ok}                                       \\
\>\>(* Immediately starts a conversation with the performer.                        \\
\>\>\> Never blocks. s is the conversations local state. *)                         \\
\>{\em end}                                                                               \\
\>addCustomerRole(S $<$:{\em Ok} \ self :T \ spec :tbcSpec.T) :CustomerRole(S)                \\
\>(* Add a customer role for conversations specified by spec to the agent.          \\
\>\> For each new started conversation a conversation private state S must          \\
\>\> be provided to startConversation() *)                                          \\
\>nilCustomerRole(S $<$:{\em Ok}) :CustomerRole(S)                                          \\
\>(* Generate a place-holder customer role. These always return                     \\
\>\> isNil() with true *)                                                           \\
\>{\em Let} PerformerRole(S $<$:{\em Ok}) $<$:{\em Ok} = {\em Tuple}                                            \\
\>\>spec() :tbcSpec.T                                                               \\
\>\>(* The bound specification for this role. *)                                    \\
\>\>isNil() :Bool                                                                   \\
\>\>(* Returns true iff role is a nil role. *)                                      \\
\>\>set(dialogName, requestName :String                                             \\
\>\>\>action(:Conversation(S)) :tbConv.Dialog) :{\em Ok}                                \\
\>\>(* action will be executed atomically whenever a customer sends this            \\
\>\>\> request in this dialog. if action returns nilDialog then                     \\
\>\>\> an asynchronous reply is allowed. *)                                         \\
\>{\em end}                                                                               \\
\>addPerformerRole(S $<$:{\em Ok} \ self :T \ spec :tbcSpec.T                                 \\
\>\> init() :S) :PerformerRole(S)                                     \\
\>(* Add a performer role for conversations specified by spec to the agent.         \\
\>\> For each new started conversation a conversation private state S is            \\
\>\> created by init() *)                                                           \\
\>nilPerformerRole(S $<$:{\em Ok}) :PerformerRole(S)                                        \\
\>(* Generate a place-holder performer role. These always return                    \\
\>\> isNil() with true *)                                                           \\
\>(* === Agent Root-Place (ubiquitous) *)                                           \\
\>currentRootPlace() :T                                                             \\
\>(* Get a handle to the current meetingPoints root place. *)                       \\
\>(* === Agent services: *)                                                         \\
\>migrateTo(self :T \ to :location.T) :{\em Ok}                                            \\
\>(* Request an agent for a migration to another location. The agent                \\
\>\> will continue its operation on the other locations site. *)                    \\
\>meet(self :T \ name :String \ spec :tbcSpec.T \ nWaitSecs :Int) :T                   \\
\>(* Resolve the agent name with respect to the current place of self               \\
\>\> and ask it for a meeting. Block max nWaitSecs unti the meet request            \\
\>\> succeeds. Returns the others agent handle. May raise meetingDenied             \\
\>\> if the meeting has been denied by the other agent or raise error               \\
\>\> if no agent could be located within nWaitSecs. *)                              \\
\>meetAndTalk(S $<$:{\em Ok} \ self :T \ name :String \ customer :CustomerRole(S)              \\
\>\>init :S \ nWaitSecs :Int) :tbConv.T(S)                                 \\
\>(* Same as meet but implicitly involve the given customer role for the            \\
\>\> conversation. This call is synchronous, e.g. will block until                  \\
\>\> the customer conversation ends. The result is the comp{\em Let}ed                    \\
\>\> conversation. May raise meetingDenied                                          \\
\>\> if the meeting has been denied by the other agent or raise error               \\
\>\> if no agent could be located within nWaitSecs. *)                              \\
\>currentLocation(:T) :location.T                                                   \\
\>(* Find out the current location for a given agent handle.                       \\
\>\> (This may or may not be possible, due to the capabilities of                   \\
\>\>\>the meetingPoint implementation, if the given agent is not                    \\
\>\>\>known locally). *)                                                            \\
\>currentPlace(:T) :T                                                               \\
\>(* Finds out the current place for a given agent handle. This will                \\
\>\> only succeed if the given agent resides in the current host. *)                \\
\>(*=== administation *)                                                            \\
\>startDomain() :{\em Ok}                                                                 \\
\>stopDomain() :{\em Ok}                                                                  \\
{\em end};                                                                                \\
\end{tabbing}
\end{xple}




