TestContainerGenerator.java revision 1d580d0f6ee4f21eb309ba7b509d2c6d671c4044 
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
17package com.google.common.collect.testing;
18
19import java.util.Collection;
20import java.util.List;
21import 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 */
33public 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