package de.uka.ipd.consensus.foundation.scoring;

import java.util.EventListener;

/**
 * The listener interface for receiving events that might change the user's score.
 * You don't have to register listeners on the several ConsensusFoundation modules,
 * but only a single <code>ScoringListener</code> on the <code>IncentiveManager</code>.
 * You can distinguish different event types with the <code>ScoringEvent.getId()</code> method.
 * 
 * <p>To register a scoring listener, create an instance of an imlementing class and register
 * it with <code>IncentiveManager.addScoringListener()</code> anytime after the <code>IncentiveManager</code>
 * has been set up successfully (e.g. in a custom <code>IncentiveManager</code> implementation at the end of an
 * overwritten <code>init()</code> or <code>initCompleted()</code> method).
 * 
 * <p>The easiest way to register scoring listeners is to add the "<code>cf.scoringlistener</code>" key
 * to the <code>ConsensusFoundation.properties</code> configuration file and list all required listener classes
 * as its value (a comma separated list):
 * <p><code>cf.scoringlistener=mypackage1.MyFirstScoringListenerImpl,mypackage2.MySecondScoringListenerImpl,...</code>
 * <p>These listeners will be loaded by <code>IncentiveManager.initCompleted()</code>. Instantiation will only be
 * successful if one of the following constructors is available (the first one that matches will be used):
 * <ul>
 *   <li><code>MyScoringListener(Properties config, ConsensusFoundationManager cfm)</code>
 *   <li><code>MyScoringListener(ConsensusFoundationManager cfm)</code>
 *   <li><code>MyScoringListener()</code>
 * </ul>
 * The <code>Properties</code> parameter contains all entries from <code>ConsensusFoundation.properties</code>.
 * 
 * @author  Thomas Much
 * @version 2006-06-14
 * @see     de.uka.ipd.consensus.foundation.scoring.IncentiveManager
 * @see     de.uka.ipd.consensus.foundation.scoring.ScoringEvent#getId()
 * @see     de.uka.ipd.consensus.foundation.ConsensusFoundation#CF_SCORING_KEY
 * @see     de.uka.ipd.consensus.foundation.ConsensusFoundationManager
 */
public interface ScoringListener extends EventListener {

	/**
	 * In this method a ScoringListener can change the user's score. It is called by the IncentiveManager.
	 * @see   de.uka.ipd.consensus.foundation.schema.User#getScore()
	 * @see   de.uka.ipd.consensus.foundation.schema.User#setScore(double)
	 */
	public void score(ScoringEvent event);
	
	
	/**
	 * <p>This method is called after all listener's <code>score()</code> methods have been called for this ScoringEvent.</p>
	 * <p>Do <b>not</b> change the user's score here! This method is intended to be used for calculations based upon the
	 * finished scoring for this ScoringEvent, e.g. calculating the user's roles/rights.</p>
	 * @see   de.uka.ipd.consensus.foundation.schema.User#getScore()
	 */
	public void scored(ScoringEvent event);

}
