org.decisiondeck.jmcda.persist.xmcda2
Class XMCDAAlternatives

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

public class XMCDAAlternatives
extends XMCDAHelperWithVarious

Methods for reading alternatives from XMCDA fragments, and writing (sets of) alternatives to XMCDA.

Nested Class Summary

static class

XMCDAAlternatives.AlternativesParsingMethod

Constructor Summary

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

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

Method Summary

Set<Alternative>	getAlternativesMarkedReal() Retrieves the subset of alternatives stored in this object that are marked as being real.
Map<Alternative,Boolean>	getFictiveStatus() Retrieves a writeable view to the status of the alternatives, observed during a read(org.decisiondeck.jmcda.persist.xmcda2.generated.XAlternative) or stored after a setFictiveStatus(Set, Set).
Set<Alternative>	getInactiveAlternatives() Retrieves the alternatives stored in this object as inactive.
Set<Alternative>	getMarkedAlternatives(XAlternativeType.Enum type) Retrieves the subset of alternatives stored in this object that are marked as requested.
Map<Alternative,String>	getNames() Retrieves a writeable view of the set of the alternative names stored in this object, observed during a read(org.decisiondeck.jmcda.persist.xmcda2.generated.XAlternative) or stored after a setNames(java.util.Map).
Set<Alternative>	keepOnly(Set<Alternative> alternatives, boolean fictitious) Returns a new set containing all the alternatives in the given set that are marked in this object as being fictive, or the complementary, those that are not marked as being fictive, depending on the value of the boolean parameter.
static Set<Alternative>	read(Collection<XAlternatives> xAlternativesCollection, XAlternativeType.Enum type, XMCDAAlternatives.AlternativesParsingMethod parsingMethod) Returns all the alternatives found in the given XMCDA fragments, or a part of these, depending on the requested parsing method.
Alternative	read(XAlternative xAlternative) Returns an alternative corresponding to the given XMCDA alternative.
Set<Alternative>	readAll(Collection<XAlternatives> xAlternativesList) Returns all the alternatives found in the given XMCDA fragments, except those marked as inactive.
Set<Alternative>	readAll(XAlternatives xAlternatives) Returns all the alternatives found in the given XMCDA fragment, except those marked as inactive.
Set<Alternative>	readUsingConcept(Collection<XAlternatives> xAlternativesList, XAlternativeType.Enum type) Returns some of the alternatives found in the given XMCDA fragments, reading only the alternatives found in tags named after the appropriate concept (fictive or real), depending on the requested type.
Set<Alternative>	readUsingMarking(Collection<XAlternatives> xAlternativesList, XAlternativeType.Enum type) Returns some of the alternatives found in the given XMCDA fragments.
void	setFictiveStatus(Set<Alternative> realAlternatives, Set<Alternative> fictiveAlternatives) Marks the given alternatives as real or fictive, for storing in this object.
void	setInactiveAlternatives(Set<Alternative> inactiveAlternatives) Stores the given alternatives in this object.
void	setMarkActiveAlternatives(boolean activeAlternatives)
void	setNames(Map<Alternative,String> names) Sets the alternative names stored in this object as the given names.
XAlternatives	writeAlternatives(Set<Alternative> alternatives, XAlternativeType.Enum type) Retrieves the XMCDA equivalent of the given alternatives.

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

XMCDAAlternatives

public XMCDAAlternatives()

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

XMCDAAlternatives

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

readUsingConcept

public Set<Alternative> readUsingConcept(Collection<XAlternatives> xAlternativesList,
                                         XAlternativeType.Enum type)
                                  throws InvalidInputException

Returns some of the alternatives found in the given XMCDA fragments, reading only the alternatives found in tags named after the appropriate concept (fictive or real), depending on the requested type. The alternative names, if found, are stored in this object, as well as the information of whether an alternative is marked fictive. Alternatives marked as inactive are stored in this object but are not included in the returned set. Any previously stored information is deleted.

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

This method expects each alternative to have an id set, and maximum one type. 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:

xAlternativesList - not null.

type - not null, XAlternativeType.REAL or XAlternativeType.FICTIVE.

Returns:

may be empty, but not null.

Throws:

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

keepOnly

public Set<Alternative> keepOnly(Set<Alternative> alternatives,
                                 boolean fictitious)

Returns a new set containing all the alternatives in the given set that are marked in this object as being fictive, or the complementary, those that are not marked as being fictive, depending on the value of the boolean parameter. See also getFictiveStatus(). Note that this is not symmetric: this method considers an alternative as being by default non fictive.

The iteration order of the returned set matches that of the given set of alternatives.

Parameters:

alternatives - not null.

fictitious - true to receive only the alternatives specifically marked as fictive, false to receive only alternatives not specifically marked as fictive.

Returns:

a new set, not null, may be empty.

getAlternativesMarkedReal

public Set<Alternative> getAlternativesMarkedReal()

Retrieves the subset of alternatives stored in this object that are marked as being real. The returned set is necessarily empty if no read(org.decisiondeck.jmcda.persist.xmcda2.generated.XAlternative) or setFictiveStatus(java.util.Set, java.util.Set) occurred yet.

Returns:

not null.

getFictiveStatus

public Map<Alternative,Boolean> getFictiveStatus()

Retrieves a writeable view to the status of the alternatives, observed during a read(org.decisiondeck.jmcda.persist.xmcda2.generated.XAlternative) or stored after a setFictiveStatus(Set, Set). The returned map has no null key, no null values, and such entries may not be added to the map.

Entries with a value true are the alternatives marked fictive, entries with a value false are marked real. Missing entries have no mark.

Returns:

not null.

setFictiveStatus

public void setFictiveStatus(Set<Alternative> realAlternatives,
                             Set<Alternative> fictiveAlternatives)

Marks the given alternatives as real or fictive, for storing in this object. No reference is held to the given sets. The sets must be disjoints.

Parameters:

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

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

See Also:

writeAlternatives(java.util.Set, org.decisiondeck.jmcda.persist.xmcda2.generated.XAlternativeType.Enum)

read

public Alternative read(XAlternative xAlternative)
                 throws InvalidInputException

Returns an alternative corresponding to the given XMCDA alternative. The name, if found, is stored in this object. If the given alternative is marked as being fictive, or as being non fictive, this is also stored in this object. If the alternative is marked as inactive, null is returned, but the alternative is added to the inactive alternatives stored in this object.

This method expects the alternative to have an id set, and maximum one type. In case of unexpected data, an exception is thrown if this object follows the XMCDAErrorsManager.ErrorManagement.THROW strategy, otherwise, this method returns null if the id could not be read.

Parameters:

xAlternative - not null.

Returns:

possibly null if unexpected content has been read and this object follows a permissive strategy, or if the given xml alternative is marked as inactive.

Throws:

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

See Also:

getInactiveAlternatives()

readAll

public Set<Alternative> readAll(XAlternatives xAlternatives)
                         throws InvalidInputException

Returns all the alternatives found in the given XMCDA fragment, except those marked as inactive. The alternative names, if found, are stored in this object, as well as the information of whether an alternative is fictive. Alternatives marked as inactive are stored in this object. Any previously stored information is deleted.

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

This method expects each alternative to have an id set, and maximum one type. 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:

xAlternatives - not null.

Returns:

may be empty, but not null.

Throws:

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

writeAlternatives

public XAlternatives writeAlternatives(Set<Alternative> alternatives,
                                       XAlternativeType.Enum type)

Retrieves the XMCDA equivalent of the given alternatives. For each alternative, also writes the name and the fictive and active status of the alternative if they are known to this object. Optionally, this method may also associate a concept to the returned tag according to the given type.

Parameters:

alternatives - not null, may be empty.

type - may be null.

Returns:

not null.

See Also:

setFictiveStatus(java.util.Set, java.util.Set), setNames(java.util.Map), setInactiveAlternatives(java.util.Set)

setMarkActiveAlternatives

public void setMarkActiveAlternatives(boolean activeAlternatives)

Parameters:

activeAlternatives - true to mark the alternatives as active when they are not found in the inactive alternatives. The default is to only mark inactive alternatives.

See Also:

setInactiveAlternatives(Set)

getNames

public Map<Alternative,String> getNames()

Retrieves a writeable view of the set of the alternative names stored in this object, observed during a read(org.decisiondeck.jmcda.persist.xmcda2.generated.XAlternative) or stored after a setNames(java.util.Map). The returned map has no null key, no null values, and such entries may not be added to the map..

Returns:

not null.

readAll

public Set<Alternative> readAll(Collection<XAlternatives> xAlternativesList)
                         throws InvalidInputException

Returns all the alternatives found in the given XMCDA fragments, except those marked as inactive. The alternative names, if found, are stored in this object, as well as the information of whether an alternative is fictive. Alternatives marked as inactive are stored in this object. Any previously stored information is deleted.

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

This method expects each alternative to have an id set, and maximum one type. 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:

xAlternativesList - not null.

Returns:

may be empty, but not null.

Throws:

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

setNames

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

Sets the alternative 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.

See Also:

writeAlternatives(java.util.Set, org.decisiondeck.jmcda.persist.xmcda2.generated.XAlternativeType.Enum)

getMarkedAlternatives

public Set<Alternative> getMarkedAlternatives(XAlternativeType.Enum type)

Retrieves the subset of alternatives stored in this object that are marked as requested. The returned set is necessarily empty if no read(org.decisiondeck.jmcda.persist.xmcda2.generated.XAlternative) or setFictiveStatus(java.util.Set, java.util.Set) occurred yet.

Parameters:

type - not null, XAlternativeType.FICTIVE or XAlternativeType.REAL.

Returns:

not null.

readUsingMarking

public Set<Alternative> readUsingMarking(Collection<XAlternatives> xAlternativesList,
                                         XAlternativeType.Enum type)
                                  throws InvalidInputException

Returns some of the alternatives found in the given XMCDA fragments. The alternative names, if found, are stored in this object, as well as the information of whether an alternative is fictive. Alternatives marked as inactive are stored in this object but are not included in the returned set. Any previously stored information is deleted.

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

This method expects each alternative to have an id set, and maximum one type. 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:

xAlternativesList - not null.

type - not null, XAlternativeType.FICTIVE to receive only the alternatives specifically marked as fictive, XAlternativeType.REAL to receive only alternatives not specifically marked as fictive. Note that this is not symmetric: this method considers an alternative as being by default non fictive.

Returns:

may be empty, but not null.

Throws:

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

read

public static Set<Alternative> read(Collection<XAlternatives> xAlternativesCollection,
                                    XAlternativeType.Enum type,
                                    XMCDAAlternatives.AlternativesParsingMethod parsingMethod)
                             throws InvalidInputException

Returns all the alternatives found in the given XMCDA fragments, or a part of these, depending on the requested parsing method. Alternatives marked as inactive are not returned.

• If the parsing method is XMCDAAlternatives.AlternativesParsingMethod.TAKE_ALL, all the alternatives are returned.
• If it is XMCDAAlternatives.AlternativesParsingMethod.SEEK_CONCEPT, only the alternatives found in tags named after the appropriate concept (fictive or real), depending on the requested type, are returned.
• If it is XMCDAAlternatives.AlternativesParsingMethod.USE_MARKING, and the type is XAlternativeType.FICTIVE, the alternatives specifically marked as fictive, accross all the XMCDA fragments, are returned. If it is XMCDAAlternatives.AlternativesParsingMethod.USE_MARKING and the type is XAlternativeType.REAL, the alternatives not specifically marked as fictive, accross all the XMCDA fragments, are returned. Note that this is not symmetric: this method considers an alternative as being by default non fictive.

For each alternative contained in the returned set, the alternative name, if found, as well as the information of whether an alternative is fictive, are stored in this object. Any previously stored information is deleted.

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

This method expects each alternative to have an id set, and maximum one type. 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:

xAlternativesCollection - not null.

type - unused and may be null if parsing method is XMCDAAlternatives.AlternativesParsingMethod.TAKE_ALL, otherwise, must be one of XAlternativeType.REAL or XAlternativeType.FICTIVE.

parsingMethod - not null.

Returns:

may be empty, but not null.

Throws:

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

See Also:

readAll(Collection), #readUsingConcept(Collection, Enum), #readUsingMarking(Collection, Enum)

getInactiveAlternatives

public Set<Alternative> getInactiveAlternatives()

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

Returns:

not null.

setInactiveAlternatives

public void setInactiveAlternatives(Set<Alternative> inactiveAlternatives)

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

Parameters:

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

See Also:

writeAlternatives(java.util.Set, org.decisiondeck.jmcda.persist.xmcda2.generated.XAlternativeType.Enum)