package geniusweb.protocol;
import com.fasterxml.jackson.annotation.JsonAutoDetect;
import com.fasterxml.jackson.annotation.JsonAutoDetect.Visibility;
import com.fasterxml.jackson.annotation.JsonSubTypes;
import com.fasterxml.jackson.annotation.JsonSubTypes.Type;
import com.fasterxml.jackson.annotation.JsonTypeInfo;
import geniusweb.connection.ConnectionFactory;
import geniusweb.deadline.Deadline;
import geniusweb.events.CurrentState;
import geniusweb.events.ProtocolEvent;
import geniusweb.protocol.partyconnection.ProtocolToPartyConnFactory;
import geniusweb.protocol.session.SessionProtocol;
import geniusweb.protocol.session.SessionState;
import geniusweb.protocol.tournament.TournamentProtocol;
import geniusweb.references.PartyWithProfile;
import geniusweb.references.ProtocolRef;
import geniusweb.references.Reference;
import tudelft.utilities.listener.Listenable;
/**
* Abstract interface to all negotiation protocols, both single session and
* tournaments. Generally a protocol handles events on the provided connections
* according to the rules set by the protocol. The rules are explained by
* {@link #getDescription()}. A protocol reports the progress through its
* {@link Listenable} interface.
*
* Because a protocol contains an internal state, it can be used only once. *
* The protocol can emit a {@link CurrentState} event at any time. It should do * so at least once, to log the final outcome of the nego. *
*
* Normally the constructor will receive a {@link ConnectionFactory} through
* which it can resolve received {@link Reference}s.
* First call to instances must be
* {@link #start(ProtocolToPartyConnFactory)}.
*
*
* All protocol implementations must ensure that the deadline is kept and that
* the session ends at the agreed time {@link Deadline#getDuration()}. This is
* to ensure that the negotiation ends and resources are freed up at or before
* some known time.
*
*/
@JsonAutoDetect(fieldVisibility = Visibility.ANY, getterVisibility = Visibility.NONE, setterVisibility = Visibility.NONE, isGetterVisibility = Visibility.NONE)
@JsonTypeInfo(use = JsonTypeInfo.Id.NAME, include = JsonTypeInfo.As.WRAPPER_OBJECT)
@JsonSubTypes({ @Type(value = SessionProtocol.class),
@Type(value = TournamentProtocol.class) })
public interface NegoProtocol extends Listenable
*
* The protocol implementation should not start any real work (eg making
* connections) before this point. That also allows us to construct protocol
* instances just to fetch the description.
*
*
* All errors are to be handled through {@link SessionState#getResult()}
* except for bugs that use {@link RuntimeException} like
* {@link IllegalArgumentException}s.
* The protocol usually uses the incoming connections to keep running. It
* does not need to run in a separate thread or so.
*
*
* @param connectionfactory the {@link ProtocolToPartyConnFactory} that
* allows the protocol to connect with the
* {@link Reference}s in the settings
*/
void start(ProtocolToPartyConnFactory connectionfactory);
/**
*
* @return a complete description of how this protocol behaves. Presented to
* the end users who should know negotiation basics but not all
* technical terms.
*/
String getDescription();
/**
* @return current state: the results of all sessions run so far and how to
* continue from that point. Changes over time as the session
* proceeds. Errors are also stored in the state.
*/
NegoState getState();
/**
*
* @return the {@link ProtocolRef} for this protocol
*/
ProtocolRef getRef();
/**
* Add a party after the protocol has started. Only some protocols can
* handle this call. Usual protocols take the settings with their
* constructor.
*
* @param party the {@link PartyWithProfile} to be added.
*/
void addParticipant(PartyWithProfile party);
}