Java

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
import java.util.Collection;
21
import java.util.List;
22
import java.util.Map;
23
import org.checkerframework.checker.nullness.qual.Nullable;
24

25
/**
26
 * To be implemented by test generators of things that can contain elements. Such things include
27
 * both {@link Collection} and {@link Map}; since there isn't an established collective noun that
28
 * encompasses both of these, 'container' is used.
29
 *
30
 * @author George van den Driessche
31
 */
32
@GwtCompatible
33
@ElementTypesAreNonnullByDefault
34
public interface TestContainerGenerator<T, E extends @Nullable Object> {
35
  /** Returns the sample elements that this generate populates its container with. */
36
  SampleElements<E> samples();
37

38
  /**
39
   * Creates a new container containing the given elements. TODO: would be nice to figure out how to
40
   * use E... or E[] as a parameter type, but this doesn't seem to work because Java creates an
41
   * array of the erased type.
42
   */
43
  T create(Object... elements);
44

45
  /**
46
   * Helper method to create an array of the appropriate type used by this generator. The returned
47
   * array will contain only nulls.
48
   */
49
  E[] createArray(int length);
50

51
  /**
52
   * Returns the iteration ordering of elements, given the order in which they were added to the
53
   * container. This method may return the original list unchanged, the original list modified in
54
   * place, or a different list.
55
   *
56
   * <p>If the order is non-deterministic, as with {@link java.util.HashSet}, this method can return
57
   * its input unmodified. Provided that the test suite is built without {@link
58
   * com.google.common.collect.testing.features.CollectionFeature#KNOWN_ORDER}, the tests will look
59
   * only at the returned contents without regard for order.
60
   */
61
  Iterable<E> order(List<E> insertionOrder);
62
}
63