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