package geniusweb.party;

import geniusweb.actions.Action;
import geniusweb.connection.Connectable;
import geniusweb.connection.ConnectionEnd;
import geniusweb.inform.Inform;

/**
 * This is a interface definition for java-based party implementations that are
 * to be run on the PartiesServer.
 * 
 * To implement a party to run on the PartiesServer, you must implement this and
 * also have a 0-arg constructor. Also we strongly recommend not to use any
 * static code blocks or do anything serious in the constructor. Instances of
 * your class may also be created only to call the getCapabilities function.
 * 
 * <h2>Short outline</h2> After the party is created (empty constructor) it is
 * first connected through a call to connect (from the {@link Connectable}
 * interface). The party can subscribe to receive {@link Inform} objects using
 * {@link ConnectionEnd#addListener(tudelft.utilities.listener.Listener)}. The
 * party can also send its actions using {@link ConnectionEnd#send(Object)}.
 * 
 * The {@link ConnectionEnd} allows the party to receive Inform objects and send
 * action objects.
 * 
 * Incoming Inform objects (eg "Settings" containing the profile, and
 * "yourturn") are notified to the party throught he notifyChange() call to the
 * party.
 * <p>
 * Outgoing Action objects (eg "Offer") are sent using the send() command.
 * 
 * Most parties extend {@link DefaultParty} to handle these connection details.
 * <p>
 * Technical details: normally a Party will be spawned inside a PartiesFactory,
 * and incoming/outgoing calls are routed through a websocket there. But in
 * testing the Connectable is often mocked.
 * 
 */
public interface Party extends Connectable<Inform, Action> {

	/**
	 * @return the capabilities of this party.
	 */
	Capabilities getCapabilities();

	/**
	 * 
	 * @return some useful short description, eg "tit-for-tat with bayesian
	 *         opponent modeling".
	 */
	String getDescription();

	/**
	 * When this is called, the party must free up all its claimed resources
	 * (memory, CPU, files, etc) immediately. This call can come in at any time
	 * (when a negotiation is aborted early), even while your party is still
	 * working on something else. Other parties for the next session may be
	 * started within a few seconds after this request to your party. The exact
	 * time is decided by the partyserver you use but typically 2 seconds. Not
	 * respecting this call and continue using the system resources will
	 * deteriorate performance of other parties running on the same machine,
	 * which may be against the assignment/competition rules.
	 */
	void terminate();
}