org.decisiondeck.jmcda.persist.xmcda2
Class XMCDACategories

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

public class XMCDACategories
extends XMCDAHelperWithVarious

Methods for reading and writing categories, including relations between categories and profiles defining them, from and to XMCDA fragments.

Constructor Summary

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

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

Method Summary

Set<Category>	getCategories() Retrieves a writeable view to the categories stored in this object.
Set<Category>	getInactiveCategories() Retrieves the categories stored in this object as inactive.
Set<Alternative>	getProfiles() Retrieves a writeable view to the profiles stored in this object.
NavigableSet<Category>	read(XCategories xCategories) Retrieves the categories found in the given fragment in the order defined by their rank, from the worst category (having the greatest number as a rank), to the best one (having the smallest number as a rank).
ICatsAndProfs	read(XCategoriesProfiles xCategoriesProfiles) Retrieves the categories found in the given fragment together with their relations with the profiles defining them, if found in the given fragment.
ICatsAndProfs	readUsingCategories(XCategoriesProfiles xCategoriesProfiles) Retrieves the categories found in the given fragment together with their relations with the profiles defining them, if found in the given fragment.
void	setCategories(Set<Category> categories) Sets the categories stored in this object.
void	setProfiles(Set<Alternative> profiles) Sets the profiles stored in this object.
XCategoriesProfiles	write(ICatsAndProfs catsAndProfs) Retrieves an XMCDA representation of the given categories and profiles.
XCategories	write(NavigableSet<Category> categories) Retrieves an XMCDA representation of the given categories.
XCategoriesComparisons	writeComparisons(NavigableSet<Category> categories) Retrieves an XMCDA representation of the given categories.

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

XMCDACategories

public XMCDACategories()

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

XMCDACategories

public XMCDACategories(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

getInactiveCategories

public Set<Category> getInactiveCategories()

Retrieves the categories stored in this object as inactive. The returned set is necessarily empty if no read occurred yet.

Returns:

not null.

read

public NavigableSet<Category> read(XCategories xCategories)
                            throws InvalidInputException

Retrieves the categories found in the given fragment in the order defined by their rank, from the worst category (having the greatest number as a rank), to the best one (having the smallest number as a rank). This method only keeps the rank order, the values of the ranks per se are lost. Categories marked as inactive in the given fragment are stored in this object but are not returned.

This method expects the categories to have an id and a rank 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.

A copy of the returned categories is stored in this object, this replaces any categories previously stored in this object.

Parameters:

xCategories - not null.

Returns:

not null.

Throws:

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

readUsingCategories

public ICatsAndProfs readUsingCategories(XCategoriesProfiles xCategoriesProfiles)
                                  throws InvalidInputException

Retrieves the categories found in the given fragment together with their relations with the profiles defining them, if found in the given fragment.

This method expects that the categories read in the given XMCDA fragment are included in the set of categories stored in this object. 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.

The returned object contains all the categories stored in this object, in order from worst to best, even if they have not been all read. This does not however imply that the returned object is complete as assessed per ICatsAndProfs.isComplete().

Parameters:

xCategoriesProfiles - not null.

Returns:

not null.

Throws:

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

See Also:

read(XCategories), getCategories(), setCategories(java.util.Set), read(XCategoriesProfiles)

write

public XCategories write(NavigableSet<Category> categories)

Retrieves an XMCDA representation of the given categories.

Parameters:

categories - not null, the categories from the worst one to the best one.

Returns:

not null.

write

public XCategoriesProfiles write(ICatsAndProfs catsAndProfs)

Retrieves an XMCDA representation of the given categories and profiles. The returned XMCDA fragment contains the associations between the categories and the profiles, for each profile in the given ICatsAndProfs object. The profiles are written in order from worst to best: this order is considered as more intuitive because the category limits must be written with lower category first.

Each profile must have a down and an up category. Ensuring that the given object is complete, as per ICatsAndProfs.isComplete(), is a sufficient condition, although not necessary.

Parameters:

catsAndProfs - not null, may not contain profiles not related to two categories.

Returns:

not null.

getCategories

public Set<Category> getCategories()

Retrieves a writeable view to the categories stored in this object. The set is empty if no read or set occurred. The returned set does not accept null entries.

Returns:

not null.

setCategories

public void setCategories(Set<Category> categories)

Sets the categories stored in this object. The iteration order of the given set is reflected in the order of the categories stored in this object.

Parameters:

categories - not null, no null entries.

getProfiles

public Set<Alternative> getProfiles()

Retrieves a writeable view to the profiles stored in this object. The set is empty if no read or set occurred. The returned set does not accept null entries.

Returns:

not null.

setProfiles

public void setProfiles(Set<Alternative> profiles)

Sets the profiles stored in this object.

Parameters:

profiles - not null, no null entries.

read

public ICatsAndProfs read(XCategoriesProfiles xCategoriesProfiles)
                   throws InvalidInputException

Retrieves the categories found in the given fragment together with their relations with the profiles defining them, if found in the given fragment.

This method expects that the categories and profiles read in the given XMCDA fragment define a complete set of categories with profiles, as defined in ICatsAndProfs.isComplete(). In case of unexpected data, an exception is thrown if this object follows the XMCDAErrorsManager.ErrorManagement.THROW strategy, otherwise, non conforming informations is skipped, and an empty ICatsAndProfs object is returned if this method can't figure out the total ordering of the categories and profiles. This happens for example if the profiles all have different associated categories. Suppose the given fragment contains two profiles having each one associated down and one associated up categories, with four different categories: in such a case, there is no way this method can guess which profile is the worst one.

Parameters:

xCategoriesProfiles - not null.

Returns:

not null, guaranteed to be a complete object (as defined in ICatsAndProfs) if no unexpected content has been read.

Throws:

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

writeComparisons

public XCategoriesComparisons writeComparisons(NavigableSet<Category> categories)

Retrieves an XMCDA representation of the given categories. The given set may be empty in which case the returned xml fragment is still a valid XMCDA fragment.

Parameters:

categories - not null, the categories from the worst one to the best one.

Returns:

not null, empty if the input set is empty (this is a valid XMCDA content).