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. <br>
 * <h2>General information</h2>
 * 
 * A protocol is mutable because the incoming connections cause state changes.
 * But it is recommended to push changing properties into the state so that the
 * complete state can be recovered and analysed.
 * <p>
 * Because a protocol contains an internal state, it can be used only once.
 * <p>
 * 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.
 * <p>
 * 
 * Normally the constructor will receive a {@link ConnectionFactory} through
 * which it can resolve received {@link Reference}s. <br>
 * First call to instances <b>must be</b>
 * {@link #start(ProtocolToPartyConnFactory)}.
 * 
 * <h2>Ensure time deadline</h2>
 * 
 * The protocol also needs to keep an eye on the deadline and take appropriate
 * actions when the deadline is reached. <br>
 * <p>
 * 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<ProtocolEvent> {
	/**
	 * Start the protocol: make connection with parties and follow the protocol.
	 * This must be called once and should be the first call after construction.
	 * <p>
	 * 
	 * 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.
	 * <p>
	 * 
	 * All errors are to be handled through {@link SessionState#getResult()}
	 * except for bugs that use {@link RuntimeException} like
	 * {@link IllegalArgumentException}s. <br>
	 * 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);

}