1 /* 2 * Copyright (C) 2008 The Guava Authors 3 * 4 * Licensed under the Apache License, Version 2.0 (the "License"); 5 * you may not use this file except in compliance with the License. 6 * You may obtain a copy of the License at 7 * 8 * http://www.apache.org/licenses/LICENSE-2.0 9 * 10 * Unless required by applicable law or agreed to in writing, software 11 * distributed under the License is distributed on an "AS IS" BASIS, 12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 * See the License for the specific language governing permissions and 14 * limitations under the License. 15 */ 16 17 package com.google.common.collect.testing; 18 19 import com.google.common.annotations.GwtCompatible; 20 21 import java.util.Collection; 22 import java.util.List; 23 import java.util.Map; 24 25 /** 26 * To be implemented by test generators of things that can contain 27 * elements. Such things include both {@link Collection} and {@link Map}; since 28 * there isn't an established collective noun that encompasses both of these, 29 * 'container' is used. 30 * 31 * @author George van den Driessche 32 */ 33 @GwtCompatible 34 public interface TestContainerGenerator<T, E> { 35 /** 36 * Returns the sample elements that this generate populates its container 37 * with. 38 */ samples()39 SampleElements<E> samples(); 40 41 /** 42 * Creates a new container containing the given elements. TODO: would be nice 43 * to figure out how to use E... or E[] as a parameter type, but this doesn't 44 * seem to work because Java creates an array of the erased type. 45 */ create(Object .... elements)46 T create(Object ... elements); 47 48 /** 49 * Helper method to create an array of the appropriate type used by this 50 * generator. The returned array will contain only nulls. 51 */ createArray(int length)52 E[] createArray(int length); 53 54 /** 55 * Returns the iteration ordering of elements, given the order in 56 * which they were added to the container. This method may return the 57 * original list unchanged, the original list modified in place, or a 58 * different list. 59 * 60 * <p>This method runs only when {@link 61 * com.google.common.collect.testing.features.CollectionFeature#KNOWN_ORDER} 62 * is specified when creating the test suite. It should never run when testing 63 * containers such as {@link java.util.HashSet}, which have a 64 * non-deterministic iteration order. 65 */ order(List<E> insertionOrder)66 Iterable<E> order(List<E> insertionOrder); 67 } 68