Home | History | Annotate | Download | only in testing 
      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 java.util.Collection;
     20 import java.util.List;
     21 import java.util.Map;
     22 
     23 /**
     24  * To be implemented by test generators of things that can contain
     25  * elements. Such things include both {@link Collection} and {@link Map}; since
     26  * there isn't an established collective noun that encompasses both of these,
     27  * 'container' is used.
     28  *
     29  * <p>This class is GWT compatible.
     30  *
     31  * @author George van den Driessche
     32  */
     33 public interface TestContainerGenerator<T, E> {
     34   /**
     35    * Returns the sample elements that this generate populates its container
     36    * with.
     37    */
     38   SampleElements<E> samples();
     39 
     40   /**
     41    * Creates a new container containing the given elements. TODO: would be nice
     42    * to figure out how to use E... or E[] as a parameter type, but this doesn't
     43    * seem to work because Java creates an array of the erased type.
     44    */
     45   T create(Object ... elements);
     46 
     47   /**
     48    * Helper method to create an array of the appropriate type used by this
     49    * generator. The returned array will contain only nulls.
     50    */
     51   E[] createArray(int length);
     52 
     53   /**
     54    * Returns the iteration ordering of elements, given the order in
     55    * which they were added to the container. This method may return the
     56    * original list unchanged, the original list modified in place, or a
     57    * different list.
     58    *
     59    * <p>This method runs only when {@link
     60    * com.google.common.collect.testing.features.CollectionFeature#KNOWN_ORDER}
     61    * is specified when creating the test suite. It should never run when testing
     62    * containers such as {@link java.util.HashSet}, which have a
     63    * non-deterministic iteration order.
     64    */
     65   Iterable<E> order(List<E> insertionOrder);
     66 }
     67