org.decision_deck.jmcda.structure.weights.Weights Maven / Gradle / Ivy
Show all versions of base Show documentation
package org.decision_deck.jmcda.structure.weights;
import java.util.Map;
import org.decision_deck.jmcda.structure.Criterion;
/**
*
* A set of criteria weights (retrievable by their respective criterion). This object allows to check whether this set
* of weights is normalized, and to retrieve the equivalent set after normalization.
*
*
* This map never contains null key or values.
*
*
* @author Olivier Cailloux
*
*/
public interface Weights extends Map {
public boolean approxEquals(Weights w2, double tolerance);
/**
*
* A weight instance equals a map of criterion and double values iff they contain the same weight mappings, thus the
* same values for the same criteria.
*
*
* This definition of equals is a consequence of this object being a Map.
*
*/
@Override
public boolean equals(Object obj);
/**
*
* Provides a read-only view of these weight values, normalized, thus where each weight value is divided by the sum
* of the weights.
*
*
* The returned object shares its tolerance value with this object.
*
*
* Note that the returned object does not necessarily give weight values that sum exactly to one, because of the
* precision error. It is unclear whether it is possible to guarantee that the returned object provides a sum of
* weights which is not further to one than this object provided sum of weights. This implication maybe holds, but
* we are unsure. If you are knowledgable in IEEE double precision properties, please let us know.
*
*
* Warning: this is currently not implemented as a view. The returned object is only valid as long as this
* object' state does not change. Copy the returned object into a new structure or use it immediately.
*
*
*
* @return a set of normalized weights.
*/
public Weights getNormalized();
/**
* Retrieves the sum of the weights this object contains.
*
* @return a number greater than or equal to zero.
*/
public double getSum();
/**
* Retrieves the weight bound to the given criterion. The criterion must have a weight, or equivalently, must be in
* the key set of this map.
*
* @param criterion
* not null.
* @return a number greater than or equal to zero.
* @see #keySet()
*/
public double getWeightBetter(Criterion criterion);
/**
* Associates the given weight to the given criterion. This method is equivalent to the
* {@link #put(Criterion, Double)} method, but this one makes it clear that null values are not
* accepted.
*
* @param criterion
* the criterion to consider. Not null.
* @param weight
* the weight to associate to the given criterion.
* @return the weight that was previously associated to that criterion, or null if there was no.
* @see #put(Criterion, Double)
*/
public Double putWeight(Criterion criterion, double weight);
}