org.decisiondeck.jmcda.persist
Class IrisExporter

java.lang.Object
  org.decisiondeck.jmcda.persist.IrisExporter

All Implemented Interfaces:

Flushable

public class IrisExporter
extends Object
implements Flushable

Exports a (possibly partial) preference model and assignment examples to multiple categories to a file suitable for import into the IRIS software.

Most knowledge of the file format used in this method comes from the IRIS manual, 1.0, Jan 2002, INESC Coimbra. A few informations have been discovered by trial and error (e.g. the fact that at least two categories must be included). Note that the IRIS software exports document in a so-called "version 2" including more information than what is exported by this class, e.g. the veto thresholds, but we have found no documentation about that format. It is currently not used by this exporter.

It is suggested to use the ASCII character set as for the provided writer. This class, when using the default export settings, does not attempt to write anything outside of that character set. Fiddling with the export settings may invalidate this.

When choosing a name for a destination file, consider using the .tri extension which is typical.

Input data used and ignored are the following.

• All criteria must have a preference direction;
• the alternatives and profiles evaluations must be complete;
• the profiles must be completely ordered (in the categories and profiles object) and ordered in a way compatible with the dominance relation of their evaluations;
• no criteria may have a veto threshold: this is not exported, this constraint permits to ensure that the user of this object is aware of this;
• all alternatives must be assigned (this is not enforced if this object is asked to be nice);
• all given weights must be between zero and one (this is not enforced if this object is asked to be nice), note however that weights must not necessarily be all given (or even given at all), which explains why this object may not proceed to systematic weights normalization;
• all alternatives must be assigned to categories that constitute an interval of categories, thus the set of categories may not contain “holes” (this is not enforced if this object is asked to be nice);
• the set of alternatives, criteria, or profiles may not be empty (this is not enforced if this object is asked to be nice), note that this implies that at least two categories have to be used;
• all criteria must have a preference and indifference threshold (this is not enforced if this object is asked to be nice), which may be zero.

The alternatives and criteria ids are not used because the IRIS file format expects consecutive integer ids, not string ids. This object will convert the alternatives and criteria to ids by ordering them using their natural ordering and numbering them from zero. To use compatible string ids, it is suggested to name your alternatives Alt000, Alt001, etc., so that the natural ordering will reflect the integer ids attribution.

If a writer is bound to this object, this object does not close it: it is considered to be the responsibility of the user who allocated the writer. If however an OutputSupplier is bound to this object, this object closes any writer it allocates. The second usage strategy is recommended as it provides guaranteed closing.

Constructor Summary

IrisExporter(OutputSupplier<? extends Writer> writerSupplier)

IrisExporter(Writer writer)

Method Summary

void	export(ISortingResultsToMultiple source) Writes the data found in the given source as an IRIS stream to the underlying writer.
void	flush()
boolean	isNice()
void	setNice(boolean nice) When this object is set to be nice, this method will try to export the file even if some data is missing, thereby rendering a file which is not valid for import but which can be examined by a user to see what data is missing.

Methods inherited from class java.lang.Object

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

Constructor Detail

IrisExporter

public IrisExporter(Writer writer)

Parameters:

writer - not null.

IrisExporter

public IrisExporter(OutputSupplier<? extends Writer> writerSupplier)

Parameters:

writerSupplier - not null.

Method Detail

isNice

public boolean isNice()

setNice

public void setNice(boolean nice)

When this object is set to be nice, this method will try to export the file even if some data is missing, thereby rendering a file which is not valid for import but which can be examined by a user to see what data is missing. If false (the default), this object will throw an exception if a required data is missing. Note that when this method is nice, it can produce a file which make IRIS loop forever (e.g. try to produce a file with no profiles). And be warned that IRIS sometimes displays misleading error messages when the input file is incorrect.

Parameters:

nice - true to kindly ask this object to be nice.

flush

public void flush()
           throws IOException

Specified by:

flush in interface Flushable

Throws:

IOException

export

public void export(ISortingResultsToMultiple source)
            throws InvalidInputException,
                   IOException

Writes the data found in the given source as an IRIS stream to the underlying writer. The writer is flushed when this method returns. If the bound writer is an OutputSupplier, the obtained writer is closed when this method returns.

Parameters:

source - not null.

Throws:

InvalidInputException - if one of the following holds:

• some criteria miss a preference direction;
• the alternatives of profiles evaluations are incomplete;
• the profiles are not completely ordered, or ordered in a way incompatible with the dominance relation on their evaluations;
• some criteria have a veto threshold;
• some alternatives are not assigned (this is not enforced if this object is asked to be nice);
• some weights are not between zero and one (this is not enforced if this object is asked to be nice);
• some alternatives are assigned to categories that do not form an interval of categories, thus the set of categories contain some “holes” (this is not enforced if this object is asked to be nice);
• the set of alternatives, criteria, or profiles, is empty (this is not enforced if this object is asked to be nice);
• some criteria have missing preference or indifference threshold (this is not enforced if this object is asked to be nice).

IOException - if an exception occurs while writing to the underlying writer.