001/* 002 * Licensed to the Apache Software Foundation (ASF) under one or more 003 * contributor license agreements. See the NOTICE file distributed with 004 * this work for additional information regarding copyright ownership. 005 * The ASF licenses this file to You under the Apache License, Version 2.0 006 * (the "License"); you may not use this file except in compliance with 007 * the License. You may obtain a copy of the License at 008 * 009 * http://www.apache.org/licenses/LICENSE-2.0 010 * 011 * Unless required by applicable law or agreed to in writing, software 012 * distributed under the License is distributed on an "AS IS" BASIS, 013 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 014 * See the License for the specific language governing permissions and 015 * limitations under the License. 016 */ 017 018package org.apache.commons.rng.sampling; 019 020import java.util.Collection; 021import java.util.List; 022import java.util.ArrayList; 023 024import org.apache.commons.rng.UniformRandomProvider; 025 026/** 027 * Sampling from a {@link Collection}. 028 * 029 * <p>Sampling uses {@link UniformRandomProvider#nextInt(int)}.</p> 030 * 031 * @param <T> Type of items in the collection. 032 * 033 * @since 1.0 034 */ 035public class CollectionSampler<T> implements SharedStateObjectSampler<T> { 036 /** Collection to be sampled from. */ 037 private final List<T> items; 038 /** RNG. */ 039 private final UniformRandomProvider rng; 040 041 /** 042 * Creates a sampler. 043 * 044 * @param rng Generator of uniformly distributed random numbers. 045 * @param collection Collection to be sampled. 046 * A (shallow) copy will be stored in the created instance. 047 * @throws IllegalArgumentException if {@code collection} is empty. 048 */ 049 public CollectionSampler(UniformRandomProvider rng, 050 Collection<T> collection) { 051 this(rng, toList(collection)); 052 } 053 054 /** 055 * @param rng Generator of uniformly distributed random numbers. 056 * @param collection Collection to be sampled. 057 */ 058 private CollectionSampler(UniformRandomProvider rng, 059 List<T> collection) { 060 this.rng = rng; 061 items = collection; 062 } 063 064 /** 065 * Picks one of the items from the 066 * {@link #CollectionSampler(UniformRandomProvider,Collection) 067 * collection passed to the constructor}. 068 * 069 * @return a random sample. 070 */ 071 @Override 072 public T sample() { 073 return items.get(rng.nextInt(items.size())); 074 } 075 076 /** 077 * {@inheritDoc} 078 * 079 * @since 1.3 080 */ 081 @Override 082 public CollectionSampler<T> withUniformRandomProvider(UniformRandomProvider rng) { 083 return new CollectionSampler<>(rng, this.items); 084 } 085 086 /** 087 * Convert the collection to a list (shallow) copy. 088 * 089 * <p>This method exists to raise an exception before invocation of the 090 * private constructor; this mitigates Finalizer attacks 091 * (see SpotBugs CT_CONSTRUCTOR_THROW). 092 * 093 * @param <T> Type of items in the collection. 094 * @param collection Collection. 095 * @return the list copy 096 * @throws IllegalArgumentException if {@code collection} is empty. 097 */ 098 private static <T> List<T> toList(Collection<T> collection) { 099 if (collection.isEmpty()) { 100 throw new IllegalArgumentException("Empty collection"); 101 } 102 return new ArrayList<>(collection); 103 } 104}