org.decisiondeck.jmcda.persist.xmcda2.aggregates
Class XMCDAProblemReader

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

public class XMCDAProblemReader
extends XMCDAHelperWithVarious

A class to read classical MCDA problems defined in XMCDA documents. This class permits to read the following objects: alternatives, criteria and criteria scales, evaluations of the alternatives over the criteria, coalitions (thus weights and majority threshold), preference, indifference, and veto thresholds. This class supports the case of a single decision maker.

See Also:

org.decisiondeck.jmcda.persist.xmcda2

Constructor Summary

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

XMCDAProblemReader(InputSupplier<? extends InputStream> mainSource)
Creates a new reader with a main source.

XMCDAProblemReader(InputSupplier<? extends InputStream> mainSource, XMCDAErrorsManager errorsManager)
Creates a new reader with a main source, and delegating error management to the given error manager in case of unexpected data read.

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

Method Summary

void	clearCache() Clears the information cached in this class, resulting in the loss of any previously read information that had been remembered by this class.
boolean	equal(InputSupplier<? extends InputStream> source1, InputSupplier<? extends InputStream> source2) Tests whether two sources are equal when replacing a null source with the main source.
XMCDAAlternatives.AlternativesParsingMethod	getAlternativesParsingMethod() Retrieves the parsing method used to read alternatives.
InputSupplier<? extends InputStream>	getSourceAlternatives() Retrieves the source dedicated to alternatives.
InputSupplier<? extends InputStream>	getSourceAlternativesEvaluations() Retrieves the source dedicated to alternatives evaluations.
InputSupplier<? extends InputStream>	getSourceCoalitions() Retrieves the source dedicated to coalitions.
InputSupplier<? extends InputStream>	getSourceCriteria() Retrieves the source dedicated to criteria.
InputSupplier<? extends InputStream>	getSourceMain() Retrieves the main source.
String	getSourceVersion() Retrieves the XMCDA version of the documents read by this object.
XMCDADoc.XMCDA	getXMCDA(InputSupplier<? extends InputStream> source) Retrieves the XMCDA document from the given source or from the main source if the given source is null.
Set<Alternative>	readAlternatives() Reads the alternatives from the dedicated source, or from the the main source if the dedicated source is not set, or retrieves the results of the previous read if it ended successfully.
ICoalitions	readCoalitions() Reads the coalitions from the dedicated source, or from the the main source if the dedicated source is not set, or retrieves the results of the previous read if it ended successfully.
Set<Criterion>	readCriteria() Reads the criteria from the dedicated source, or from the the main source if the dedicated source is not set, or retrieves the results of the previous read if it ended successfully.
IRdEvaluations	readEvaluations() Reads the alternatives evaluations from the dedicated source, or from the the main source if the dedicated source is not set, or retrieves the results of the previous read if it ended successfully.
Map<Criterion,IOrderedInterval>	readScales() Reads the scales from the dedicated source, or from the the main source if the dedicated source is not set, or retrieves the results of the previous read if it ended successfully.
ICriteriaWithThresholds	readThresholds() Reads the thresholds from the dedicated source, or from the the main source if the dedicated source is not set, or retrieves the results of the previous read if it ended successfully.
void	setAlternativesParsingMethod(XMCDAAlternatives.AlternativesParsingMethod alternativesParsingMethod) Sets the parsing method used to read alternatives.
void	setSourceAlternatives(InputSupplier<? extends InputStream> sourceAlternatives) Sets the dedicated source used to read alternatives.
void	setSourceAlternativesEvaluations(InputSupplier<? extends InputStream> sourceAlternativesEvaluations) Sets the dedicated source used to read the evaluations.
void	setSourceCoalitions(InputSupplier<? extends InputStream> sourceCoalitions) Sets the dedicated source used to read the coalitions.
void	setSourceCriteria(InputSupplier<? extends InputStream> sourceCriteria) Sets the dedicated source used to read the criteria.
void	setSourceMain(InputSupplier<? extends InputStream> sourceMain) Sets the main source used to read all types of objects for which no dedicated source is set.

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

Constructor Detail

XMCDAProblemReader

public XMCDAProblemReader()

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

XMCDAProblemReader

public XMCDAProblemReader(InputSupplier<? extends InputStream> mainSource)

Creates a new reader with a main source. The reader will use the default error management strategy XMCDAErrorsManager.ErrorManagement.THROW.

Parameters:

mainSource - not null.

XMCDAProblemReader

public XMCDAProblemReader(XMCDAErrorsManager errorsManager)

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

Parameters:

errorsManager - not null.

XMCDAProblemReader

public XMCDAProblemReader(InputSupplier<? extends InputStream> mainSource,
                          XMCDAErrorsManager errorsManager)

Creates a new reader with a main source, and delegating error management to the given error manager in case of unexpected data read.

Parameters:

mainSource - not null.

errorsManager - not null.

Method Detail

clearCache

public void clearCache()

Clears the information cached in this class, resulting in the loss of any previously read information that had been remembered by this class. After this method is called, using any read method results in an effective read of the relevant source instead of a possible re-use of the cached data.

getSourceVersion

public String getSourceVersion()

Retrieves the XMCDA version of the documents read by this object.

Returns:

null if not uniform or nothing read yet.

getSourceAlternatives

public InputSupplier<? extends InputStream> getSourceAlternatives()

Retrieves the source dedicated to alternatives.

Returns:

null if not set.

setSourceAlternatives

public void setSourceAlternatives(InputSupplier<? extends InputStream> sourceAlternatives)

Sets the dedicated source used to read alternatives.

Parameters:

sourceAlternatives - null for not set.

getSourceAlternativesEvaluations

public InputSupplier<? extends InputStream> getSourceAlternativesEvaluations()

Retrieves the source dedicated to alternatives evaluations.

Returns:

null if not set.

setSourceAlternativesEvaluations

public void setSourceAlternativesEvaluations(InputSupplier<? extends InputStream> sourceAlternativesEvaluations)

Sets the dedicated source used to read the evaluations.

Parameters:

sourceAlternativesEvaluations - null for not set.

getSourceCoalitions

public InputSupplier<? extends InputStream> getSourceCoalitions()

Retrieves the source dedicated to coalitions.

Returns:

null if not set.

setSourceCoalitions

public void setSourceCoalitions(InputSupplier<? extends InputStream> sourceCoalitions)

Sets the dedicated source used to read the coalitions.

Parameters:

sourceCoalitions - null for not set.

getSourceCriteria

public InputSupplier<? extends InputStream> getSourceCriteria()

Retrieves the source dedicated to criteria.

Returns:

null if not set.

setSourceCriteria

public void setSourceCriteria(InputSupplier<? extends InputStream> sourceCriteria)

Sets the dedicated source used to read the criteria.

Parameters:

sourceCriteria - null for not set.

getSourceMain

public InputSupplier<? extends InputStream> getSourceMain()

Retrieves the main source. This is used to read any type of object when the dedicated source is not set.

Returns:

null if not set.

setSourceMain

public void setSourceMain(InputSupplier<? extends InputStream> sourceMain)

Sets the main source used to read all types of objects for which no dedicated source is set.

Parameters:

sourceMain - null for not set.

getAlternativesParsingMethod

public XMCDAAlternatives.AlternativesParsingMethod getAlternativesParsingMethod()

Retrieves the parsing method used to read alternatives.

Returns:

the parsing method.

setAlternativesParsingMethod

public void setAlternativesParsingMethod(XMCDAAlternatives.AlternativesParsingMethod alternativesParsingMethod)

Sets the parsing method used to read alternatives.

Parameters:

alternativesParsingMethod - not null.

getXMCDA

public XMCDADoc.XMCDA getXMCDA(InputSupplier<? extends InputStream> source)
                        throws IOException,
                               XmlException

Retrieves the XMCDA document from the given source or from the main source if the given source is null. Ensures that it contains an XMCDA document conforming to the XMCDA schema.

Parameters:

source - may be null, in which case the main source in this object must be non null.

Returns:

null iff the given source and the main source are null.

Throws:

IOException - if an exception happens while opening or closing the given reader, or while parsing the source.

XmlException - if an exception related to the contents of the source happens while parsing the source, including if the given source does not contain a valid XMCDA document.

readAlternatives

public Set<Alternative> readAlternatives()
                                  throws IOException,
                                         XmlException,
                                         InvalidInputException

Reads the alternatives from the dedicated source, or from the the main source if the dedicated source is not set, or retrieves the results of the previous read if it ended successfully. Which alternatives are returned depend on the chosen parsing method.

The returned set iteration order matches the order of the source.

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

Returns:

not null.

Throws:

IOException - if an exception happens while opening or closing the given reader, or while parsing the source.

XmlException - if an exception related to the xml correctness of the source happens while parsing the source, including if the given source does not contain a valid XMCDA document.

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

See Also:

#setAlternativesParsingMethod(AlternativesParsingMethod)

readEvaluations

public IRdEvaluations readEvaluations()
                               throws IOException,
                                      XmlException,
                                      InvalidInputException

Reads the alternatives evaluations from the dedicated source, or from the the main source if the dedicated source is not set, or retrieves the results of the previous read if it ended successfully. This method returns every evaluations found, with no distinction between REAL and FICTIVE alternatives.

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

Returns:

not null.

Throws:

IOException - if an exception happens while opening or closing the given reader, or while parsing the source.

XmlException - if an exception related to the xml correctness of the source happens while parsing the source, including if the given source does not contain a valid XMCDA document.

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

readCoalitions

public ICoalitions readCoalitions()
                           throws IOException,
                                  XmlException,
                                  InvalidInputException

Reads the coalitions from the dedicated source, or from the the main source if the dedicated source is not set, or retrieves the results of the previous read if it ended successfully.

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

Returns:

not null.

Throws:

IOException - if an exception happens while opening or closing the given reader, or while parsing the source.

XmlException - if an exception related to the xml correctness of the source happens while parsing the source, including if the given source does not contain a valid XMCDA document.

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

readCriteria

public Set<Criterion> readCriteria()
                            throws IOException,
                                   XmlException,
                                   InvalidInputException

Reads the criteria from the dedicated source, or from the the main source if the dedicated source is not set, or retrieves the results of the previous read if it ended successfully. This method also sets the scales and thresholds in this object.

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

Returns:

not null.

Throws:

IOException - if an exception happens while opening or closing the given reader, or while parsing the source.

XmlException - if an exception related to the xml correctness of the source happens while parsing the source, including if the given source does not contain a valid XMCDA document.

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

readScales

public Map<Criterion,IOrderedInterval> readScales()
                                           throws IOException,
                                                  XmlException,
                                                  InvalidInputException

Reads the scales from the dedicated source, or from the the main source if the dedicated source is not set, or retrieves the results of the previous read if it ended successfully.

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

Returns:

not null.

Throws:

IOException - if an exception happens while opening or closing the given reader, or while parsing the source.

XmlException - if an exception related to the xml correctness of the source happens while parsing the source, including if the given source does not contain a valid XMCDA document.

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

readThresholds

public ICriteriaWithThresholds readThresholds()
                                       throws IOException,
                                              XmlException,
                                              InvalidInputException

Reads the thresholds from the dedicated source, or from the the main source if the dedicated source is not set, or retrieves the results of the previous read if it ended successfully.

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

Returns:

not null.

Throws:

IOException - if an exception happens while opening or closing the given reader, or while parsing the source.

XmlException - if an exception related to the xml correctness of the source happens while parsing the source, including if the given source does not contain a valid XMCDA document.

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

equal

public boolean equal(InputSupplier<? extends InputStream> source1,
                     InputSupplier<? extends InputStream> source2)

Tests whether two sources are equal when replacing a null source with the main source. If both resulting sources are null, this method returns true. This method can be used to test whether the effective sources that this reader will use are equal.

Parameters:

source1 - may be null.

source2 - may be null.

Returns:

true iff both sources are equal from the point of view of this class.