org.decisiondeck.jmcda.persist.xmcda2
Class XMCDACriteria

java.lang.Object
  org.decisiondeck.jmcda.persist.xmcda2.utils.XMCDAHelper
      org.decisiondeck.jmcda.persist.xmcda2.utils.XMCDAHelperWithVarious
          org.decisiondeck.jmcda.persist.xmcda2.XMCDACriteria

public class XMCDACriteria
extends XMCDAHelperWithVarious

Methods for reading and writing criteria and related informations from and to XMCDA fragments.

Nested Class Summary

static class

XMCDACriteria.IsContinuousInterval A predicate that returns true if the given interval is not null and is continuous, thus, has no step size.

Field Summary

static String	INDIFFERENCE_CONCEPT_STRING
static String	PREFERENCE_CONCEPT_STRING
static String	VETO_CONCEPT_STRING
static String	WEIGHTS_CONCEPT_STRING

Constructor Summary

XMCDACriteria()
Creates a new object which will use the default error management strategy XMCDAErrorsManager.ErrorManagement.THROW.

XMCDACriteria(XMCDAErrorsManager errorsManager)
Creates a new object delegating error management to the given error manager in case of unexpected data read.

Method Summary

Set<Criterion>	getCriteria() Retrieves a copy of the set of criteria read after the last call to read(XCriteria), with the iteration order reflecting the order of reading.
Set<Criterion>	getInactiveCriteria() Retrieves the criteria stored in this object as inactive.
Map<Criterion,Double>	getIndifferenceThresholds() Retrieves a writeable view to the criteria indifference thresholds.
Map<Criterion,String>	getNames() Retrieves a writeable view to the criteria names.
Map<Criterion,Double>	getPreferenceThresholds() Retrieves a writeable view to the criteria preference thresholds.
Map<Criterion,IOrderedInterval>	getScales() Retrieves a writeable view to the criteria scales.
ICriteriaWithThresholds	getThresholds() TODO this should be a writeable view, other methods should be removed.
Map<Criterion,Double>	getVetoThresholds() Retrieves a writeable view to the criteria veto thresholds.
boolean	mightBeCoalitionsPerDecisionMaker(Collection<XCriteriaSet> xAllCriteriaSet) Tests whether the given XMCDA fragment possibly contains coalitions informations per decision maker.
Set<Criterion>	read(XCriteria xCriteria) Retrieves the set of criteria contained into the given XMCDA fragment, except those marked as inactive.
Set<Criterion>	readAll(Collection<XCriteria> xAllCriteria) Retrieves the set of criteria contained into the given XMCDA fragments, except for the criteria marked as inactive.
Map<DecisionMaker,ICoalitions>	readAllCoalitions(Collection<XCriteriaSet> xAllCriteriaSet) Retrieves the coalitions, thus the weights and the majority threshold, per decision makers, found in the given XMCDA fragments.
Coalitions	readCoalitions(XCriteriaSet xCriteriaSet) Retrieves the coalitions, thus the weights and the majority threshold, found in the given XMCDA fragment.
Weights	readWeights(Collection<XCriteriaValues> xCriteriaValuesList) Retrieves the weights from the XMCDA fragment among the given collection that has the MCDA concept corresponding to the WEIGHTS_CONCEPT_STRING.
Weights	readWeights(XCriteriaSet xCriteriaSet) Retrieves the weights found in the given XMCDA fragment.
Weights	readWeights(XCriteriaValues xCriteriaValues) Retrieves the weights found in the given XMCDA fragment.
void	setCriteriaOrder(Collection<Criterion> criteriaOrder)
void	setDmsOrder(Collection<DecisionMaker> dmsOrder)
void	setInactiveCriteria(Set<Criterion> inactiveCriteria) Stores the given criteria in this object.
void	setIndifferenceThresholds(Map<Criterion,Double> indifferenceThresholds) Sets the criteria indifference thresholds stored in this object as the given ones.
void	setNames(Map<Criterion,String> names) Sets the criteria names stored in this object as the given names.
void	setPreferenceThresholds(Map<Criterion,Double> preferenceThresholds) Sets the criteria preference thresholds stored in this object as the given ones.
void	setScales(Map<Criterion,IOrderedInterval> scales) Sets the criteria scales stored in this object as the given ones.
void	setVetoThresholds(Map<Criterion,Double> vetoThresholds) Sets the criteria veto thresholds stored in this object as the given ones.
List<XCriteriaSet>	write(Map<DecisionMaker,ICoalitions> allCoalitions) Retrieves the XMCDA equivalent of the given collection of coalitions, as a collection of XCriteriaSet, each one being associated to the corresponding decision maker in the given input.
XCriteria	write(Set<Criterion> source) Retrieves an XMCDA fragment containing the given criteria, together with name, scale and preference, indifference, veto thresholds, if set in this object.
static XCriteria	write(Set<Criterion> source, Map<Criterion,IOrderedInterval> scales, ICriteriaWithThresholds thresholds) Retrieves an XMCDA fragment containing the given criteria, together with scale and preference, indifference, veto thresholds, if defined.
XCriteriaSet	write(Weights source) Retrieves the XMCDA equivalent of the given weights.
XCriteriaSet	writeCoalitions(ICoalitions source) Retrieves the XMCDA equivalent of the given coalitions.

Methods inherited from class org.decisiondeck.jmcda.persist.xmcda2.utils.XMCDAHelper

error, getStrategy, setStrategy

Methods inherited from class java.lang.Object

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

Field Detail

INDIFFERENCE_CONCEPT_STRING

public static final String INDIFFERENCE_CONCEPT_STRING

See Also:

Constant Field Values

PREFERENCE_CONCEPT_STRING

public static final String PREFERENCE_CONCEPT_STRING

See Also:

Constant Field Values

VETO_CONCEPT_STRING

public static final String VETO_CONCEPT_STRING

See Also:

Constant Field Values

WEIGHTS_CONCEPT_STRING

public static final String WEIGHTS_CONCEPT_STRING

See Also:

Constant Field Values

Constructor Detail

XMCDACriteria

public XMCDACriteria()

Creates a new object which will use the default error management strategy XMCDAErrorsManager.ErrorManagement.THROW.

XMCDACriteria

public XMCDACriteria(XMCDAErrorsManager errorsManager)

Creates a new object delegating error management to the given error manager in case of unexpected data read.

Parameters:

errorsManager - not null.

Method Detail

write

public static XCriteria write(Set<Criterion> source,
                              Map<Criterion,IOrderedInterval> scales,
                              ICriteriaWithThresholds thresholds)

Retrieves an XMCDA fragment containing the given criteria, together with scale and preference, indifference, veto thresholds, if defined. If some scales or thresholds do not correspond to a criterion of the given source criteria, it is not taken into account. The scales and thresholds informations are not expected to be complete, some may be missing.

The scales used as values in the given scales map and corresponding to a criterion in the given set must be continuous scales, thus must have no step size. Discrete scales are not currently supported.

Parameters:

source - not null.

scales - possibly null; may miss elements.

thresholds - possibly null; may miss elements.

Returns:

not null.

See Also:

write(Set)

write

public XCriteria write(Set<Criterion> source)

Retrieves an XMCDA fragment containing the given criteria, together with name, scale and preference, indifference, veto thresholds, if set in this object. If some name, scale or threshold set in this object do not correspond to a criterion of the given source criteria, it is not taken into account. The names, scales and thresholds informations are not expected to be complete, some may be missing.

Parameters:

source - not null.

Returns:

not null.

See Also:

setNames(java.util.Map), setScales(java.util.Map), setPreferenceThresholds(java.util.Map), setIndifferenceThresholds(java.util.Map), setVetoThresholds(java.util.Map)

getNames

public Map<Criterion,String> getNames()

Retrieves a writeable view to the criteria names. The returned map has no null key, no null values, and such entries may not be added to the map.

Returns:

not null.

getThresholds

public ICriteriaWithThresholds getThresholds()

TODO this should be a writeable view, other methods should be removed. Retrieves a copy of the criteria thresholds.

Returns:

not null.

setNames

public void setNames(Map<Criterion,String> names)

Sets the criteria names stored in this object as the given names. No reference is held to the given map.

Parameters:

names - not null, may be empty, no null key or value.

getPreferenceThresholds

public Map<Criterion,Double> getPreferenceThresholds()

Retrieves a writeable view to the criteria preference thresholds. The returned map has no null key, no null values, and such entries may not be added to the map.

Returns:

not null.

setPreferenceThresholds

public void setPreferenceThresholds(Map<Criterion,Double> preferenceThresholds)

Sets the criteria preference thresholds stored in this object as the given ones. No reference is held to the given map.

Parameters:

preferenceThresholds - not null, may be empty, must contain no null key or values.

getIndifferenceThresholds

public Map<Criterion,Double> getIndifferenceThresholds()

Retrieves a writeable view to the criteria indifference thresholds. The returned map has no null key, no null values, and such entries may not be added to the map.

Returns:

not null.

setIndifferenceThresholds

public void setIndifferenceThresholds(Map<Criterion,Double> indifferenceThresholds)

Sets the criteria indifference thresholds stored in this object as the given ones. No reference is held to the given map.

Parameters:

indifferenceThresholds - not null, may be empty, must contain no null key or values.

getVetoThresholds

public Map<Criterion,Double> getVetoThresholds()

Retrieves a writeable view to the criteria veto thresholds. The returned map has no null key, no null values, and such entries may not be added to the map.

Returns:

not null.

setVetoThresholds

public void setVetoThresholds(Map<Criterion,Double> vetoThresholds)

Sets the criteria veto thresholds stored in this object as the given ones. No reference is held to the given map.

Parameters:

vetoThresholds - not null, may be empty, must contain no null key or values.

read

public Set<Criterion> read(XCriteria xCriteria)
                    throws InvalidInputException

Retrieves the set of criteria contained into the given XMCDA fragment, except those marked as inactive. The iteration order of the returned set matches the reading order.

This object keeps a copy of the informations just read: the names, the scales, the thresholds of the criteria, as well as a copy of the set of criteria itself, and a copy of the inactive criteria. Previously existing informations, that have been set or that have been read previously, are deleted before reading.

In case of unexpected data, an exception is thrown if this object follows the XMCDAErrorsManager.ErrorManagement.THROW strategy, otherwise, non conforming informations will be skipped.

Parameters:

xCriteria - not null.

Returns:

a copy of the set of criteria just read and kept in this object; not null.

Throws:

InvalidInputException - iff unexpected content has been read and this object follows the XMCDAErrorsManager.ErrorManagement.THROW strategy.

See Also:

getCriteria(), getNames(), getScales(), getPreferenceThresholds(), getIndifferenceThresholds(), getVetoThresholds()

readAll

public Set<Criterion> readAll(Collection<XCriteria> xAllCriteria)
                       throws InvalidInputException

Retrieves the set of criteria contained into the given XMCDA fragments, except for the criteria marked as inactive. The iteration order of the returned set matches the reading order.

This object keeps a copy of the informations just read: the names, the scales, the thresholds of the criteria, as well as a copy of the set of criteria itself and a separate copy of the inactive criteria. Previously existing informations, that have been set or that have been read previously, are deleted before reading.

In case of unexpected data, an exception is thrown if this object follows the XMCDAErrorsManager.ErrorManagement.THROW strategy, otherwise, non conforming informations will be skipped.

Parameters:

xAllCriteria - not null.

Returns:

a copy of the set of criteria just read and kept in this object; not null.

Throws:

InvalidInputException - iff unexpected content has been read and this object follows the XMCDAErrorsManager.ErrorManagement.THROW strategy.

See Also:

getCriteria(), getNames(), getScales(), getPreferenceThresholds(), getIndifferenceThresholds(), getVetoThresholds()

getCriteria

public Set<Criterion> getCriteria()

Retrieves a copy of the set of criteria read after the last call to read(XCriteria), with the iteration order reflecting the order of reading. If no read has occurred yet, an empty set is returned.

Returns:

not null.

readWeights

public Weights readWeights(XCriteriaValues xCriteriaValues)
                    throws InvalidInputException

Retrieves the weights found in the given XMCDA fragment.

In case of unexpected data, an exception is thrown if this object follows the XMCDAErrorsManager.ErrorManagement.THROW strategy, otherwise, non conforming informations will be skipped.

Parameters:

xCriteriaValues - not null.

Returns:

not null, may be empty.

Throws:

InvalidInputException - iff unexpected content has been read and this object follows the XMCDAErrorsManager.ErrorManagement.THROW strategy.

readWeights

public Weights readWeights(Collection<XCriteriaValues> xCriteriaValuesList)
                    throws InvalidInputException

Retrieves the weights from the XMCDA fragment among the given collection that has the MCDA concept corresponding to the WEIGHTS_CONCEPT_STRING.

This method expects, among others, that there is exactly one such XMCDA fragment among the given collection. In case of unexpected data, an exception is thrown if this object follows the XMCDAErrorsManager.ErrorManagement.THROW strategy, otherwise, non conforming informations will be skipped.

Parameters:

xCriteriaValuesList - not null.

Returns:

not null, may be empty.

Throws:

InvalidInputException - iff unexpected content has been read and this object follows the XMCDAErrorsManager.ErrorManagement.THROW strategy.

readWeights

public Weights readWeights(XCriteriaSet xCriteriaSet)
                    throws InvalidInputException

Retrieves the weights found in the given XMCDA fragment.

In case of unexpected data, an exception is thrown if this object follows the XMCDAErrorsManager.ErrorManagement.THROW strategy, otherwise, non conforming informations will be skipped.

Parameters:

xCriteriaSet - not null.

Returns:

not null, may be empty.

Throws:

InvalidInputException - iff unexpected content has been read and this object follows the XMCDAErrorsManager.ErrorManagement.THROW strategy.

readAllCoalitions

public Map<DecisionMaker,ICoalitions> readAllCoalitions(Collection<XCriteriaSet> xAllCriteriaSet)
                                                 throws InvalidInputException

Retrieves the coalitions, thus the weights and the majority threshold, per decision makers, found in the given XMCDA fragments. The iteration order of the returned map matches that of the given collection.

This object expects, among others, the majority thresholds to be set. In case of unexpected data, an exception is thrown if this object follows the XMCDAErrorsManager.ErrorManagement.THROW strategy, otherwise, non conforming informations will be skipped.

Parameters:

xAllCriteriaSet - not null.

Returns:

not null, with no null values, but possibly with empty values. If no unexpected content have been read, the values contain at least a majority threshold.

Throws:

InvalidInputException - iff unexpected content has been read and this object follows the XMCDAErrorsManager.ErrorManagement.THROW strategy.

mightBeCoalitionsPerDecisionMaker

public boolean mightBeCoalitionsPerDecisionMaker(Collection<XCriteriaSet> xAllCriteriaSet)

Tests whether the given XMCDA fragment possibly contains coalitions informations per decision maker.

Parameters:

xAllCriteriaSet - not null.

Returns:

true iff the given collection contains more than one element or contains exactly one element which has its name set.

readCoalitions

public Coalitions readCoalitions(XCriteriaSet xCriteriaSet)
                          throws InvalidInputException

Retrieves the coalitions, thus the weights and the majority threshold, found in the given XMCDA fragment.

This object expects, among others, the majority threshold to be set. In case of unexpected data, an exception is thrown if this object follows the XMCDAErrorsManager.ErrorManagement.THROW strategy, otherwise, non conforming informations will be skipped.

Parameters:

xCriteriaSet - not null.

Returns:

not null; if no unexpected content have been read, contains at least a majority threshold.

Throws:

InvalidInputException - iff unexpected content has been read and this object follows the XMCDAErrorsManager.ErrorManagement.THROW strategy.

writeCoalitions

public XCriteriaSet writeCoalitions(ICoalitions source)

Retrieves the XMCDA equivalent of the given coalitions.

Parameters:

source - not null.

Returns:

not null.

write

public List<XCriteriaSet> write(Map<DecisionMaker,ICoalitions> allCoalitions)

Retrieves the XMCDA equivalent of the given collection of coalitions, as a collection of XCriteriaSet, each one being associated to the corresponding decision maker in the given input.

Parameters:

allCoalitions - not null, with values not null and having each a majority threshold.

Returns:

not null.

write

public XCriteriaSet write(Weights source)

Retrieves the XMCDA equivalent of the given weights.

Parameters:

source - not null.

Returns:

not null.

setScales

public void setScales(Map<Criterion,IOrderedInterval> scales)

Sets the criteria scales stored in this object as the given ones. No reference is held to the given map.

Parameters:

scales - not null, may be empty, must contain only continuous scales, thus with no step size.

getScales

public Map<Criterion,IOrderedInterval> getScales()

Retrieves a writeable view to the criteria scales. The returned map has no null key, no null values, no continuous scales, and such entries may not be added to the map.

Returns:

not null.

setCriteriaOrder

public void setCriteriaOrder(Collection<Criterion> criteriaOrder)

setDmsOrder

public void setDmsOrder(Collection<DecisionMaker> dmsOrder)

getInactiveCriteria

public Set<Criterion> getInactiveCriteria()

Retrieves the criteria stored in this object as inactive. The returned set is necessarily empty if no read or setInactiveCriteria(Set) occurred yet.

Returns:

not null.

setInactiveCriteria

public void setInactiveCriteria(Set<Criterion> inactiveCriteria)

Stores the given criteria in this object. No reference is held to the given set.

Parameters:

inactiveCriteria - not null, may be empty, no null entry.