org.decisiondeck.jmcda.structure.graph
Class Preorder<T>

java.lang.Object
  org.decisiondeck.jmcda.structure.graph.Preorder<T>

Type Parameters:

T - the type of elements on which the relation is defined.

public class Preorder<T>
extends Object

Objects of this class represent a complete preorder, that is, a relation on a set of objects called elements, which can be viewed as an ordered set of classes of equivalence. A class of equivalence is a set of elements that are considered equal by the preorder. All objects in the highest class of equivalence are given the rank number one, all elements in the second highest class of equivalence have the rank two, and so on. As of vocabulary, in this class the highest rank is considered to be the rank one, thus containing the highest elements in terms of this preorder relation.

The lowest possible rank for a set of n elements, if all ranks are occupied, is the rank n . This object does not enforce that every ranks are occupied, thus it can have more ranks than elements.

This object guarantees that any element it contains has only one rank: no two equal elements (in terms of Object.equals(java.lang.Object)) may occupy two different ranks at the same time.

Constructor Summary

Preorder(int ranks)
Creates a preorder with the given number of ranks.

Method Summary

Set<T>	get(int rank)
Integer	getRank(T element)
int	getRanksCount()
NavigableSet<T>	getTotalOrder() Retrieves this preorder content as a total order, if this preorder is a total order (i.e., if there is exactly one element per rank).
void	lower(T element) Lowers the given element by one rank.
boolean	put(Set<T> elements, int rank) Puts all the elements in the given rank, as per calling repeatedly the method put(Object, int).
boolean	put(T element, int rank) Adds an element to the set of elements at a given rank.
void	raise(T element) Raises the given element by one rank.
boolean	remove(T element) Removes the given element from this object, if it is present.

Methods inherited from class java.lang.Object

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

Constructor Detail

Preorder

public Preorder(int ranks)

Creates a preorder with the given number of ranks. All ranks are initially empty.

Parameters:

ranks - a number greater or equal to zero.

Method Detail

remove

public boolean remove(T element)

Removes the given element from this object, if it is present.

Parameters:

element - not null.

Returns:

true iff the given element existed in this object.

get

public Set<T> get(int rank)

Parameters:

rank - between 1 and the number of ranks, inclusive. 1 is the best rank.

Returns:

an unmodifiable view of the objects stored at the given rank.

put

public boolean put(T element,
                   int rank)

Adds an element to the set of elements at a given rank. If the element already existed and was at the given rank, nothing happens. If the element already existed and was at a different rank, the existing element is removed from that rank and put at the given rank instead.

Parameters:

element - not null.

rank - between 1 and the number of ranks, inclusive. 1 is the best, or highest, rank.

Returns:

true iff the element has been added or moved, thus was not already in the set of elements at that rank.

raise

public void raise(T element)

Raises the given element by one rank.

Parameters:

element - must exist in this object, must not be already at rank one.

getRank

public Integer getRank(T element)

Parameters:

element - not null.

Returns:

the rank of the given element, or null iff the given element is not contained in this object.

put

public boolean put(Set<T> elements,
                   int rank)

Puts all the elements in the given rank, as per calling repeatedly the method put(Object, int). Elements existing at an other rank are moved.

Parameters:

elements - not null, but may be empty.

rank - the rank where to put the objects.

Returns:

true iff the call changed the ranking, thus false iff every elements were already in the given rank.

lower

public void lower(T element)

Lowers the given element by one rank. If the given element has rank r, after the method returns it has rank r+1.

Parameters:

element - must exist in this object at a rank higher than the lowest one.

getRanksCount

public int getRanksCount()

Returns:

the number of available ranks in this object. This is not necessarily the number of ranks occupied.

getTotalOrder

public NavigableSet<T> getTotalOrder()

Retrieves this preorder content as a total order, if this preorder is a total order (i.e., if there is exactly one element per rank). The object ranked first is set as highest, or best. This corresponds to the last element in iteration order of the returned set, as the returned set is ordered from lowest to highest.

Returns:

null iff this preorder is not a total order.