genius.core.protocol

Interface MultilateralProtocol

All Known Implementing Classes:

AlternatingMajorityConsensusProtocol, AlternatingMultipleOffersProtocol, DefaultMultilateralProtocol, MediatorFeedbackBasedProtocol, MediatorProtocol, SimpleMediatorBasedProtocol, StackedAlternatingOffersProtocol

public interface MultilateralProtocol

The protocol describes if the negotiation is finished, what the agreement is, which actions can be done in the next round.

The protocol is executed for example by the SessionManager.

Specification

A protocol should be used as follows.

1. The first time, beforeSession(Session, List) should be called and all agents should receive the actions accordingly.
2. For each round in the session:
   1. getRoundStructure(List, Session) should be called to determine the Round
   2. For each Turn in the Round :
      1. the Turn.getParty() agent should be called with the specified allowed actions.
      2. The agent returns a picked action
      3. getActionListeners(List) should be called to get a list of which agents need to hear the picked action of this agent.
   3. isFinished(Session, List) should be checked after the round is complete to see if there are other rounds . If so, repeat
3. When a session is completely done, afterSession(Session, List) should be called

Method Summary

Modifier and Type	Method and Description
void	afterSession(Session session, java.util.List<NegotiationParty> parties) This will get called just after ending the session.
void	applyAction(Action action, Session session) Apply the action according to the protocol.
java.util.Map<NegotiationParty,java.util.List<Action>>	beforeSession(Session session, java.util.List<NegotiationParty> parties) Returns a list of Actions to be sent to NegotiationParty.receiveMessage(AgentID, Action) .
void	endNegotiation() Overwrites the rest of the protocol and sets the protocol state to finish
void	endNegotiation(java.lang.String reason) Overwrites the rest of the protocol and sets the protocol state to finish
java.util.Map<NegotiationParty,java.util.List<NegotiationParty>>	getActionListeners(java.util.List<NegotiationParty> parties) Get a map of parties that are listening to each other's response.
Bid	getCurrentAgreement(Session session, java.util.List<NegotiationParty> parties) This method should return the current agreement.
int	getNumberOfAgreeingParties(Session session, java.util.List<NegotiationParty> parties) Gets the number of parties that currently agree to the offer.
Round	getRoundStructure(java.util.List<NegotiationParty> parties, Session session) Get the structure of the current round.
boolean	isFinished(Session session, java.util.List<NegotiationParty> parties) Check if the protocol is done or still busy.

Method Detail

getRoundStructure

Round getRoundStructure(java.util.List<NegotiationParty> parties,
                        Session session)

Get the structure of the current round. Each round, this method receives a list of all the NegotiationParty and the complete Session which can be used to diversify the round structure at some point during the session.

Parameters:

parties - The parties currently participating

session - The complete session history

Returns:

A list of possible actions

beforeSession

java.util.Map<NegotiationParty,java.util.List<Action>> beforeSession(Session session,
                                                                     java.util.List<NegotiationParty> parties)
                                                              throws NegotiationPartyTimeoutException,
                                                                     java.util.concurrent.ExecutionException,
                                                                     java.lang.InterruptedException

Returns a list of Actions to be sent to NegotiationParty.receiveMessage(AgentID, Action) . This will get called just before the session starts. If some initialization with needs to be done by the protocol, it can be done here.

Parameters:

session - The upcoming Session

parties - The NegotiationPartys that will participate in the session

Throws:

NegotiationPartyTimeoutException

java.util.concurrent.ExecutionException

java.lang.InterruptedException

afterSession

void afterSession(Session session,
                  java.util.List<NegotiationParty> parties)

This will get called just after ending the session. If the protocol needs to do some post session steps, it can be done here. Protocols should not handle NegotiationParty.negotiationEnded(Bid) as these are always called by the SessionManager.

Parameters:

session - The session instance that was used for the session

parties - The parties that participated in the session

applyAction

void applyAction(Action action,
                 Session session)
          throws ActionException

Apply the action according to the protocol. All actions done by all agents come through this method. The protocol should check here if the agent's action is actually allowed and contains the proper data.

Parameters:

action - action to apply. The Agent ID in the action already has been checked when this is called.

session - the current state of this session

Throws:

ActionException - if the proposed action is illegal according to the protocol.

isFinished

boolean isFinished(Session session,
                   java.util.List<NegotiationParty> parties)

Check if the protocol is done or still busy. If this method returns true, the SessionManager will not start a new Round after the current one. It will however finish all the turns described in the getRoundStructure(java.util.List, genius.core.session.Session) method.

Parameters:

session - the current state of this session

parties - all the parties involved in the negotiation

Returns:

true if the protocol is finished

getActionListeners

java.util.Map<NegotiationParty,java.util.List<NegotiationParty>> getActionListeners(java.util.List<NegotiationParty> parties)

Get a map of parties that are listening to each other's response. All these listeners should be informed whenever a party takes an action. See also the default implementations DefaultMultilateralProtocol.listenToAll(List) and DefaultMultilateralProtocol.listenToNone(List)

Parameters:

parties - The parties involved in the current negotiation

Returns:

A map where the key is a NegotiationParty that is responding to a NegotiationParty.chooseAction(List) event, and the value is a list of NegotiationPartys that are listening to that key party's response.

getCurrentAgreement

Bid getCurrentAgreement(Session session,
                        java.util.List<NegotiationParty> parties)

This method should return the current agreement.

Some protocols only have an agreement at the negotiation session, make sure that this method returns null until the end of the session in that case, because this method might be queried at intermediary steps.

Parameters:

session - The complete session history up to this point

parties - The parties involved in the current negotiation

Returns:

The agreed upon bid or null if no agreement

getNumberOfAgreeingParties

int getNumberOfAgreeingParties(Session session,
                               java.util.List<NegotiationParty> parties)

Gets the number of parties that currently agree to the offer. For protocols that either have an agreement or not, you can set this number to 0 until an agreement is found, and then set this value to the number of parties.

Parameters:

session - the current state of this session

parties - The parties currently participating

Returns:

the number of parties agreeing to the current agreement

endNegotiation

void endNegotiation()

Overwrites the rest of the protocol and sets the protocol state to finish

endNegotiation

void endNegotiation(java.lang.String reason)

Overwrites the rest of the protocol and sets the protocol state to finish

Parameters:

reason - Optionally give a reason why the protocol is finished.