jadex.bdi.planlib.protocols
Class ProposalEvaluator

java.lang.Object
  jadex.bdi.planlib.protocols.ProposalEvaluator

All Implemented Interfaces:

IProposalEvaluator

public class ProposalEvaluator
extends java.lang.Object
implements IProposalEvaluator

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.

1. 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).
2. 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.
3. 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.

Field Summary

protected boolean	ascending Flag indicating if evaluations are rated ascending (the higher the better) or the other way round.
static java.lang.String	EVALUATION_ACCEPTABLE Evaluation value indicating an acceptable proposal that should be considered in further negotiation rounds.
protected java.util.Comparator	evaluation_comparator A comparator used for comparing evaluations.
static java.lang.String	EVALUATION_INACCEPTABLE Evaluation value indicating an inacceptable proposal that should be excluded.
protected java.lang.Object	evaluation_limit Limit determining the acceptability of an evaluation.

Constructor Summary

protected	ProposalEvaluator() Create a default proposal evaluator.
	ProposalEvaluator(java.util.Comparator evaluation_comparator, java.lang.Object evaluation_limit, boolean ascending) Create a default proposal evaluator with a given limit value.
	ProposalEvaluator(java.lang.Object evaluation_limit, boolean ascending) Create a default proposal evaluator with a given limit value.

Method Summary

protected java.lang.Object	evaluateProposal(java.lang.Object cfp, java.lang.Object cfp_info, NegotiationRecord[] history, ParticipantProposal proposal) Evaluate the given proposal.
ParticipantProposal[]	evaluateProposals(java.lang.Object cfp, java.lang.Object cfp_info, NegotiationRecord[] history, ParticipantProposal[] proposals) Evaluate the given proposals and determine winning proposals.
protected boolean	isProposalAcceptable(java.lang.Object cfp, java.lang.Object cfp_info, NegotiationRecord[] history, ParticipantProposal proposal) Check if a proposal is acceptable.
protected ParticipantProposal[]	orderAcceptables(java.lang.Object cfp, java.lang.Object cfp_info, NegotiationRecord[] history, ParticipantProposal[] proposals) Order acceptable proposals by preference.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

EVALUATION_INACCEPTABLE

public static final java.lang.String EVALUATION_INACCEPTABLE

Evaluation value indicating an inacceptable proposal that should be excluded.

See Also:

Constant Field Values

EVALUATION_ACCEPTABLE

public static final java.lang.String EVALUATION_ACCEPTABLE

Evaluation value indicating an acceptable proposal that should be considered in further negotiation rounds.

See Also:

Constant Field Values

evaluation_comparator

protected java.util.Comparator evaluation_comparator

A comparator used for comparing evaluations.

evaluation_limit

protected java.lang.Object evaluation_limit

Limit determining the acceptability of an evaluation.

ascending

protected boolean ascending

Flag indicating if evaluations are rated ascending (the higher the better) or the other way round.

Constructor Detail

ProposalEvaluator

protected ProposalEvaluator()

Create a default proposal evaluator. This (empty) constructor cannot be used directly, as it requires at least the isProposalAcceptable() method to be overwritten.

ProposalEvaluator

public ProposalEvaluator(java.lang.Object evaluation_limit,
                         boolean 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. Otherwise, the evaluateProposal() method should be overwritten to provide comparable evaluation values for the proposal objects.

Parameters:

evaluation_limit - The limit specifying which proposals are acceptable.

ascending - Sort order, which specifies that all evaluations below or equal (true) or above or equal (false) to the limit are acceptable.

ProposalEvaluator

public ProposalEvaluator(java.util.Comparator evaluation_comparator,
                         java.lang.Object evaluation_limit,
                         boolean 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.

Parameters:

evaluation_comparator - A comparator used to compare proposal evaluations.

evaluation_limit - The limit specifying which proposals are acceptable.

ascending - Sort order, which specifies that all evaluations below or equal (true) or above or equal (false) to the limit are acceptable.

Method Detail

evaluateProposals

public ParticipantProposal[] evaluateProposals(java.lang.Object cfp,
                                               java.lang.Object cfp_info,
                                               NegotiationRecord[] history,
                                               ParticipantProposal[] proposals)

Evaluate the given proposals and determine winning proposals.

Specified by:

evaluateProposals in interface IProposalEvaluator

Parameters:

cfp - The original call-for-proposal object.

cfp_info - Local meta information associated to the interaction.

history - The history of negotiation rounds.

proposals - The received proposals.

Returns:

The winners among the proposals.

evaluateProposal

protected java.lang.Object evaluateProposal(java.lang.Object cfp,
                                            java.lang.Object cfp_info,
                                            NegotiationRecord[] history,
                                            ParticipantProposal proposal)

Evaluate the given proposal. An implementation may use the defined constants for specifying evaluation results, but custom evaluation values are also allowed. This default implementation justs uses the proposal object itself as its evaluation, as long as it is comparable in itself or with a given comparator.

Parameters:

cfp - The original call-for-proposal object.

cfp_info - Local meta information associated to the interaction.

history - The history of negotiation rounds.

proposal - A received proposal.

Returns:

The proposal evaluation.

isProposalAcceptable

protected boolean isProposalAcceptable(java.lang.Object cfp,
                                       java.lang.Object cfp_info,
                                       NegotiationRecord[] history,
                                       ParticipantProposal proposal)

Check if a proposal is acceptable. This default implementation checks for one of the evaluation constants and otherwise tries to use the given evaluation limit (if any) and compares it to the proposals evaluation value. Proposals without evaluation or which are not comparable are deemed inacceptable by default.

Parameters:

cfp - The original call-for-proposal object.

cfp_info - Local meta information associated to the interaction.

history - The history of negotiation rounds.

proposal - A received proposal.

Returns:

The proposal evaluation.

orderAcceptables

protected ParticipantProposal[] orderAcceptables(java.lang.Object cfp,
                                                 java.lang.Object cfp_info,
                                                 NegotiationRecord[] history,
                                                 ParticipantProposal[] proposals)

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).

Parameters:

cfp - The original call-for-proposal object.

cfp_info - Local meta information associated to the interaction.

history - The history of negotiation rounds.

proposals - The acceptable proposals.

Returns:

The ordered acceptable proposals.