org.jamesframework.core.util

Class RouletteSelector

java.lang.Object

org.jamesframework.core.util.RouletteSelector

public class RouletteSelector
extends Object

Simulates selection based on a roulette wheel where all items have a weight expressing the size of their section of the wheel. The size of the wheel is the sum of all item weights. During selection a random number in (0, wheel size) is picked and then the item corresponding to this section of the wheel is selected.

For a set of items with equal weight they will all have the same probability of being selected. Items which are assigned higher weights will have a higher likelihood of being selected (and the opposite holds for lower weights).

The implementation is heavily inspired by original code written by the Apache Software Foundation (http://www.apache.org) for the Hadoop MapReduce project (http://hadoop.apache.org).

Author:

Herman De Beukelaer

Constructor Summary

Constructors

Constructor and Description
RouletteSelector()

Method Summary

Modifier and Type	Method and Description
static <E> E	select(List<E> items, List<Double> weights, Random random) Select an item from a given list by roulette selection, where each item has a weight expressing the size of its section of the roulette wheel.

Methods inherited from class java.lang.Object

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

Constructor Detail

RouletteSelector

public RouletteSelector()

Method Detail

select

public static <E> E select(List<E> items,
                           List<Double> weights,
                           Random random)

Select an item from a given list by roulette selection, where each item has a weight expressing the size of its section of the roulette wheel. The total size of the wheel is the sum of all item weights. The list of items and weights should be of the same size and all weights should be positive. A weight of zero is allowed, in which case the respective item will never be selected. One item is always selected, except when the item list is empty or when all weights are zero in which case null is returned.

Type Parameters:

E - type of items

Parameters:

items - items from which one is to be selected

weights - item weights (same order as items)

random - random generator (cannot be null)

Returns:

item selected by roulette selection, null if all weights are zero or the item list is empty

Throws:

IllegalArgumentException - if both lists are not of the same size or if any of the given weights is < 0

NullPointerException - if items, weights or random are null or if weights contains any null elements