/*
 * Copyright (c) 2007 Israfil Consulting Services Corporation
 * Copyright (c) 2007 Christian Edward Gruber
 * All Rights Reserved
 * 
 * This software is licensed under the Berkeley Standard Distribution license,
 * (BSD license), as defined below:
 * 
 * Redistribution and use in source and binary forms, with or without 
 * modification, are permitted provided that the following conditions are met:
 *
 * 1. Redistributions of source code must retain the above copyright notice, this 
 *    list of conditions and the following disclaimer.
 * 2. Redistributions in binary form must reproduce the above copyright notice, 
 *    this list of conditions and the following disclaimer in the documentation 
 *    and/or other materials provided with the distribution.
 * 3. Neither the name of Israfil Consulting Services nor the names of its contributors 
 *    may be used to endorse or promote products derived from this software without 
 *    specific prior written permission.
 *
 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND 
 * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED 
 * WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. 
 * IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, 
 * INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, 
 * BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, 
 * OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, 
 * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 
 * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY 
 * OF SUCH DAMAGE.
 * 
 * $Id: IterableResultSet.java 26 2006-02-13 16:35:44Z cgruber $
 */
package net.israfil.foundation.collections;

import java.security.SecureRandom;
import java.util.Collection;
import java.util.Iterator;
import java.util.Random;

/**
 * A simple wrapper that provides an Iterable implementation that wraps
 * a collection and returns a RandomOrderIterator when asked for an iterator.
 * 
 * No result set can have more than one Iterable wrapper around it at a time.
 * However, it is impossible for this object to know implicitly when it is 
 * no longer required (to free the reference).  Therefore, when this 
 * wrapper is concluded, it should be disposed of via the dispose() method.
 * 
 * @author <a href="mailto:cgruber@israfil.net">Christian Edward Gruber </a>
 */
public class RandomOrderIterable<E> implements Iterable<E> {

	private Collection<E> _collection;
	private Random _random = null;
	
	public RandomOrderIterable(Collection<E> collection) {
		_collection = collection;
	}
	
	public RandomOrderIterable(Collection<E> collection, Random random) {
		this(collection);
		_random = random;
	}

	public Iterator<E> iterator() {
		return new RandomOrderIterator<E>(_collection,(_random == null) ? new SecureRandom() : _random);
	}

}