11d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert/* 21d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * Copyright (C) 2008 The Guava Authors 31d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * 41d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * Licensed under the Apache License, Version 2.0 (the "License"); 51d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * you may not use this file except in compliance with the License. 61d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * You may obtain a copy of the License at 71d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * 81d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * http://www.apache.org/licenses/LICENSE-2.0 91d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * 101d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * Unless required by applicable law or agreed to in writing, software 111d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * distributed under the License is distributed on an "AS IS" BASIS, 121d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 131d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * See the License for the specific language governing permissions and 141d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * limitations under the License. 151d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert */ 161d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert 171d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringertpackage com.google.common.collect.testing; 181d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert 191d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringertimport java.util.Collection; 201d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringertimport java.util.List; 211d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringertimport java.util.Map; 221d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert 231d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert/** 241d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * To be implemented by test generators of things that can contain 251d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * elements. Such things include both {@link Collection} and {@link Map}; since 261d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * there isn't an established collective noun that encompasses both of these, 271d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * 'container' is used. 281d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * 291d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * <p>This class is GWT compatible. 301d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * 311d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * @author George van den Driessche 321d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert */ 331d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringertpublic interface TestContainerGenerator<T, E> { 341d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert /** 351d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * Returns the sample elements that this generate populates its container 361d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * with. 371d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert */ 381d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert SampleElements<E> samples(); 391d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert 401d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert /** 411d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * Creates a new container containing the given elements. TODO: would be nice 421d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * to figure out how to use E... or E[] as a parameter type, but this doesn't 431d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * seem to work because Java creates an array of the erased type. 441d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert */ 451d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert T create(Object ... elements); 461d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert 471d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert /** 481d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * Helper method to create an array of the appropriate type used by this 491d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * generator. The returned array will contain only nulls. 501d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert */ 511d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert E[] createArray(int length); 521d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert 531d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert /** 541d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * Returns the iteration ordering of elements, given the order in 551d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * which they were added to the container. This method may return the 561d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * original list unchanged, the original list modified in place, or a 571d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * different list. 581d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * 591d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * <p>This method runs only when {@link 601d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * com.google.common.collect.testing.features.CollectionFeature#KNOWN_ORDER} 611d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * is specified when creating the test suite. It should never run when testing 621d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * containers such as {@link java.util.HashSet}, which have a 631d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * non-deterministic iteration order. 641d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert */ 651d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert Iterable<E> order(List<E> insertionOrder); 661d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert} 67