• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
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