jadex.bdi.planlib.protocols.ProposalEvaluator Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of jadex-applications-applib-bdi Show documentation
The Jadex applib BDI package contains ready to use functionalities for BDI agents mostly in form of modules called capabilities.
The newest version!
package jadex.bdi.planlib.protocols;


import java.util.ArrayList;
import java.util.Collections;
import java.util.Comparator;
import java.util.List;

/**
 *  A default implementation of the proposal evaluator interface.
 *  The implementation determines acceptable proposals by comparing
 *  proposals or evaluations to a given limit value.
 *  
 *  
 *  The evaluation process implemented in the evaluateProposals() method
 *  is distributed across three methods, which can be separately overwritten
 *  if needed, while reusing functionality of the other methods.
 *  

 *  The proposals are evaluated
 *  	by calling the the evaluateProposal() method for each of the proposals.
 *  	The evaluation result is written back into the proposal. The
 *      default implementation just checks, if the proposal object itself
 *      is suitable as an evaluation (i.e. if it is comparable).
 *   
For each of the proposals, the acceptability is determined.
 *      By default, the given string constants are interpreted or, if
 *      a limit value is given, the proposal evaluations are compared
 *      to the limit value.
 *  
Finally, the acceptable proposals are ordered by preference.
 *      As a default, the proposals are compared to each other and sorted
 *      according to the given ordering.
 *  
 */
public class ProposalEvaluator implements IProposalEvaluator
{
	//-------- constants --------
	
	/** Evaluation value indicating an inacceptable proposal that should be excluded. */
	public static final String	EVALUATION_INACCEPTABLE	= "evaluation-inacceptable";
	
	/** Evaluation value indicating an acceptable proposal that should be considered in further negotiation rounds. */
	public static final String	EVALUATION_ACCEPTABLE	= "evaluation-acceptable";
	
	//-------- attributes --------
	
	/** A comparator used for comparing evaluations. */
	protected Comparator	evaluation_comparator;
	
	/** Limit determining the acceptability of an evaluation. */
	protected Object	evaluation_limit;
	
	/** Flag indicating if evaluations are rated ascending (the higher the better)
	    or the other way round. */
	protected boolean	ascending;

	//-------- constructors --------
	
	/**
	 *  Create a default proposal evaluator.
	 *  This (empty) constructor cannot be used directly,
	 *  as it requires at least the isProposalAcceptable() method
	 *  to be overwritten.
	 */
	protected ProposalEvaluator() {}
	
	/**
	 *  Create a default proposal evaluator with a given limit value.
	 *  This constructor can be used without overwriting any methods,
	 *  if the proposal objects are comparable to each other and the limit
	 *  value. Otherwise, the evaluateProposal() method should be overwritten
	 *  to provide comparable evaluation values for the proposal objects.
	 *  @param evaluation_limit	The limit specifying which proposals are acceptable.
	 *  @param ascending Sort order, which specifies that all evaluations below or equal (true)
	 *    or above or equal (false) to the limit are acceptable.
	 */
	public ProposalEvaluator(Object evaluation_limit, boolean ascending)
	{
		this.evaluation_limit	= evaluation_limit;
		this.ascending	= ascending;
	}

	/**
	 *  Create a default proposal evaluator with a given limit value.
	 *  This constructor can be used without overwriting any methods,
	 *  if the proposal objects are comparable to each other and the limit
	 *  value using the given comparator. Otherwise, the evaluateProposal()
	 *  method should be overwritten to provide comparable evaluation values for the proposal objects.
	 *  @param evaluation_comparator	A comparator used to compare proposal evaluations.
	 *  @param evaluation_limit	The limit specifying which proposals are acceptable.
	 *  @param ascending Sort order, which specifies that all evaluations below or equal (true)
	 *    or above or equal (false) to the limit are acceptable.
	 */
	public ProposalEvaluator(Comparator evaluation_comparator, Object evaluation_limit, boolean ascending)
	{
		this.evaluation_comparator	= evaluation_comparator;
		this.evaluation_limit	= evaluation_limit;
		this.ascending	= ascending;
	}

	//-------- IProposalEvaluator interface --------
	
	/**
	 *  Evaluate the given proposals and determine winning proposals.
	 *  @param cfp	The original call-for-proposal object.
	 *  @param cfp_info	Local meta information associated to the interaction.
	 *  @param history The history of negotiation rounds.
	 *  @param proposals The received proposals.
	 *  @return The winners among the proposals.
	 */
	public ParticipantProposal[] evaluateProposals(Object cfp, Object cfp_info, NegotiationRecord[] history, ParticipantProposal[] proposals)
	{
		// Determine evaluations for each of the proposals.
		for(int i=0; i=0;
		}
		else
		{
			ret	= false;
		}
		
		return ret;
	}
	
	/**
	 *  Order acceptable proposals by preference.
	 *  This default implementation tries to compare the proposal evaluations
	 *  directly or using the given comparator.
	 *  If some proposal evaluations are not comparable,
	 *  these are returned in the original order (after comparable proposals, if any).
	 *  @param cfp	The original call-for-proposal object.
	 *  @param cfp_info	Local meta information associated to the interaction.
	 *  @param history The history of negotiation rounds.
	 *  @param proposals The acceptable proposals.
	 *  @return The ordered acceptable proposals.
	 */
	protected ParticipantProposal[]	orderAcceptables(Object cfp, Object cfp_info, NegotiationRecord[] history, ParticipantProposal[] proposals)
	{
		List comparables	= new ArrayList();
		List uncomparables	= new ArrayList();
		for(int i=0; i