Package org.decisiondeck.jmcda.persist.xmcda2.aggregates

High level classes to export aggregate structures to, or import from, XMCDA documents.

See:
Description

Class Summary

XMCDAGroupSortingProblemReader	TODO document properly.
XMCDAProblemReader	A class to read classical MCDA problems defined in XMCDA documents.
XMCDASortingProblemReader	A class to read MCDA sorting problems defined in XMCDA documents, including the typical preferences informations related to a sorting problem, namely thresholds and coalitions; and sorting results, namely assignments.
XMCDASortingProblemWriter	A class to write MCDA sorting problems to XMCDA documents, including the typical preferences informations related to a sorting problem, namely thresholds and coalitions; and sorting results, namely assignments.

Package org.decisiondeck.jmcda.persist.xmcda2.aggregates Description

High level classes to export aggregate structures to, or import from, XMCDA documents.

This package contain reader classes designed to read complete structures from complete XMCDA documents, contrary to the lower level classes dedicated to reading and writing XMCDA fragments.

XMCDA reader objects read from so-called sources, which are InputSupplier of Reader objects. Such objects can be obtained using Guava's classes, e.g. with Files.newReaderSupplier(java.io.File, java.nio.charset.Charset), Resources.newReaderSupplier(java.net.URL, java.nio.charset.Charset). The good point with using InputSuppliers instead of Readers is that the user does not have to manage the opening and closing of the streams: the XMCDA reader takes care of this.

The problem may be defined in a single source, called the main source, representing a single XMCDA document from which everything is read. Alternatively, dedicated sources may be used for each of for some type of object to read, using the relevant setSource methods. XMCDA reader objects will default to the main source if asked to read a type for which a dedicated source has not been defined.

As with classes reading XMCDA fragments, reader classes from this package expect the XMCDA documents to comply to some grammar. When not satisfied, for example, if the document contains a value that is not a number at some place where a number was expected, the reader class will act according to one of several possible error management strategies. The default strategy is to throw an InvalidInputException. The exception comes with a message that will explain briefly which unexpected situation was met. Throwing an exception stops the reading, thus other possible errors occuring in other places in the document are omitted from the message. The user may command the reader object to use other strategies to avoid stopping reading at the first error: log all errors, or collect all errors. In the latter case, the object may (and should) be queried to retrieve all error messages after the read.

Reader objects read only once from the relevant source for each type of requested object, if the reading does not throw an exception. Second calls to the same read method, supposing the previous call was successful, will return the same object, or a new copy of the same object. Reading only once from the source permits to avoid stacking several times the same error message, supposing the error management strategy is XMCDAErrorsManager.ErrorManagement.COLLECT or XMCDAErrorsManager.ErrorManagement.LOG. Changing a dedicated source after the corresponding object type has been read is not allowed and will throw a runtime exception.

If an exception happens during a read, the state of the reader is not modified by the read and the next read will try again from scratch. Changing the dedicated or the main source is allowed before re-trying a failed read.

Unless indicated otherwise, read methods return immutable objects or defensive copies of underlying objects. Even if they constitute new copies, this should be considered an implementation detail and the objects be treated as immutable.

Reader classes will avoid reading twice the same information when possible by caching information the first time it is read. Asking for the same bit of information twice without changing the sources in between will result in only one read. The second time, the cached object will be returned.

The intended usage of these reader classes is to first set up all relevant sources, then start reading. Changing some source after some read has occurred will clear some part of the cache and possibly result in a re-read of some information, even of a non-related source. It is guaranteed that at least any cached information pertaining to a given source is cleared when that source is changed, but more cached information than only these could be cleared. Exactly which part of the cache is cleared when some source is set is undocumented and subject to change.