net.sf.mmm.util.collection.base
Class RankMap<E>

java.lang.Object
  net.sf.mmm.util.collection.base.RankMap<E>

Type Parameters:

E - is the type of the elements (decisions) to rank.

public class RankMap<E>
extends Object

This class is like a Map that maps elements (<E>) to an int value that represents the rank of the according element.
This is useful for heuristic decisions where specific detections indicate a gain or loss of a specific element (representing a decision). Additionally an element can be declared unacceptable so it is out of the decision.

Since:

1.0.1

Author:

Joerg Hohwiller (hohwille at users.sourceforge.net)

Nested Class Summary

private static class

RankMap.Ranking This inner class represents the RankMap.Ranking.rank of an element.

Field Summary

private Collection<E>	elements
private Map<E,RankMap.Ranking>	map
static int	RANK_UNACCEPTABLE The rank that represents an element that has been disqualified.

Constructor Summary

RankMap()
The constructor.

Method Summary

int	addRank(E element, int gain) This method adds the given gain to the current rank of the given element.
E	getBest() This method gets the element that has currently the best (highest) positive rank.
E	getBest(int threshold) This method gets the element that has currently the best (highest) rank greater or equal to the given threshold.
List<E>	getBests() This method gets a List containing the element(s) that has currently the best (highest) rank.
List<E>	getBetterOrEqual(int threshold) This method gets all elements with a rank greater or equal to the given threshold.
Collection<E>	getElements() This method gets all elements in this RankMap that have been actively ranked (by addRank(Object, int) or setUnacceptable(Object)).
int	getRank(E element) This method gets the current rank for the given element.
boolean	isUnacceptable(E element) This method determines if the given element has been declared unacceptable.
void	setUnacceptable(E element) This method ranks the given element as unacceptable.

Methods inherited from class java.lang.Object

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

Field Detail

RANK_UNACCEPTABLE

public static final int RANK_UNACCEPTABLE

The rank that represents an element that has been disqualified. If an element has this rank it can NOT change it again and calls to addRank(Object, int) will have no effect.

See Also:

setUnacceptable(Object), Constant Field Values

map

private final Map<E,RankMap.Ranking> map

See Also:

getRank(Object)

elements

private final Collection<E> elements

See Also:

getElements()

Constructor Detail

RankMap

public RankMap()

The constructor.

Method Detail

getElements

public Collection<E> getElements()

This method gets all elements in this RankMap that have been actively ranked (by addRank(Object, int) or setUnacceptable(Object)).

Returns:

a Collection with the ranked elements.

getRank

public int getRank(E element)

This method gets the current rank for the given element. The rank is in the range from -1 to Integer.MAX_VALUE. If the element has no rank, a value of 0 will be returned.

Parameters:

element - is the element for which the rank is requested.

Returns:

the current rank of the given element.

See Also:

RANK_UNACCEPTABLE, addRank(Object, int)

setUnacceptable

public void setUnacceptable(E element)

This method ranks the given element as unacceptable. After the call of this method the rank of the given element is set to RANK_UNACCEPTABLE and can NOT be changed again.

Parameters:

element - is the unacceptable element.

isUnacceptable

public boolean isUnacceptable(E element)

This method determines if the given element has been declared unacceptable.

Parameters:

element - is the element to check.

Returns:

true if the given element is unacceptable, false if the given element is acceptable.

addRank

public int addRank(E element,
                   int gain)

This method adds the given gain to the current rank of the given element. If the element is unacceptable, this method will have no effect. This method guarantees that there will be no overflow of the rank.

Parameters:

element - is the element to rank.

gain - is the value to add to the current rank. It may be negative to reduce the rank. A value of 0 will have no effect.

Returns:

the new rank.

getBest

public E getBest()

This method gets the element that has currently the best (highest) positive rank. If there are multiple best elements, it is unspecified which one is returned.

Returns:

the element with the best positive rank or null if there is no element with a positive rank.

See Also:

getBests()

getBest

public E getBest(int threshold)

This method gets the element that has currently the best (highest) rank greater or equal to the given threshold. If there are multiple best elements, it is unspecified which one is returned.

Parameters:

threshold - is the minimum rank accepted for the best element.

Returns:

the element with the best rank greater or equal to the given threshold or null if there is no such element.

See Also:

getBests()

getBests

public List<E> getBests()

This method gets a List containing the element(s) that has currently the best (highest) rank. If there is no element with a positive rank, an empty List will be returned. If there are multiple elements with the (same) best rank, they will all be contained in the returned List.

Returns:

the List with the best element(s).

getBetterOrEqual

public List<E> getBetterOrEqual(int threshold)

This method gets all elements with a rank greater or equal to the given threshold.

Parameters:

threshold - is the minimum accepted rank.

Returns:

the list with all elements better or equal to the given threshold.