001/* 002 * Copyright (C) 2008 The Guava Authors 003 * 004 * Licensed under the Apache License, Version 2.0 (the "License"); 005 * you may not use this file except in compliance with the License. 006 * You may obtain a copy of the License at 007 * 008 * http://www.apache.org/licenses/LICENSE-2.0 009 * 010 * Unless required by applicable law or agreed to in writing, software 011 * distributed under the License is distributed on an "AS IS" BASIS, 012 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 013 * See the License for the specific language governing permissions and 014 * limitations under the License. 015 */ 016 017package com.google.common.collect.testing; 018 019import com.google.common.annotations.GwtCompatible; 020import java.util.Collection; 021import java.util.List; 022import java.util.Map; 023 024/** 025 * To be implemented by test generators of things that can contain elements. Such things include 026 * both {@link Collection} and {@link Map}; since there isn't an established collective noun that 027 * encompasses both of these, 'container' is used. 028 * 029 * @author George van den Driessche 030 */ 031@GwtCompatible 032public interface TestContainerGenerator<T, E> { 033 /** Returns the sample elements that this generate populates its container with. */ 034 SampleElements<E> samples(); 035 036 /** 037 * Creates a new container containing the given elements. TODO: would be nice to figure out how to 038 * use E... or E[] as a parameter type, but this doesn't seem to work because Java creates an 039 * array of the erased type. 040 */ 041 T create(Object... elements); 042 043 /** 044 * Helper method to create an array of the appropriate type used by this generator. The returned 045 * array will contain only nulls. 046 */ 047 E[] createArray(int length); 048 049 /** 050 * Returns the iteration ordering of elements, given the order in which they were added to the 051 * container. This method may return the original list unchanged, the original list modified in 052 * place, or a different list. 053 * 054 * <p>If the order is non-deterministic, as with {@link java.util.HashSet}, this method can return 055 * its input unmodified. Provided that the test suite is built without {@link 056 * com.google.common.collect.testing.features.CollectionFeature#KNOWN_ORDER}, the tests will look 057 * only at the returned contents without regard for order. 058 */ 059 Iterable<E> order(List<E> insertionOrder); 060}