Package org.instancio.generator.hints

Class CollectionHint

java.lang.Object
org.instancio.generator.hints.CollectionHint
All Implemented Interfaces:
Hint<CollectionHint>
public final class CollectionHint extends Object implements Hint<CollectionHint>
This hint is for generators that create collections.

The responsibility of a generator is to provide an instance of a collection to the engine. The collection may be partially populated (with expected data). The engine takes care of populating the collection with additional elements.

Sample use case

The goal is to set up a collection with a couple of expected objects and let the engine populate the rest of the collection with random data.

This can be achieved as follows: 


 class PhonesGenerator implements Generator<List<Phone>> {

     @Override
     public List<Phone> generate(Random random) {
         List<Phone> list = new ArrayList<>();
         list.add(Phone.builder().number("111-222-3333").phoneType(PhoneType.CELL).build());
         list.add(Phone.builder().number("111-444-5555").build()); // phoneType is null, but will be populated
         return list;
     }

     @Override
     public Hints hints() {
         return Hints.builder()
                  // tells the engine to populate null fields in the objects created in the generate() method
                 .afterGenerate(AfterGenerate.POPULATE_NULLS)
                 .with(CollectionHint.builder()
                          // number of additional elements to be generated and added to the collection by the engine
                         .generateElements(3)
                         .shuffle(true) // shuffle the collection once populated
                         .build())
                 .build();
     }
 }

 // Generator usage
 Person person = Instancio.of(Person.class)
         .supply(field("phoneNumbers"), new PhonesGenerator())
         .create();

 // Expected results
 assertThat(person.getAddress().getPhoneNumbers())
         .hasSize(5)
         .doesNotContainNull()
         .anyMatch(p -> p.getNumber().equals("111-222-3333") && p.getPhoneType() == PhoneType.CELL)
         .anyMatch(p -> p.getNumber().equals("111-444-5555") && p.getPhoneType() != null); // phoneType populated

Summary of results:

  • The generated collection contains our custom objects as well as generated phone objects.
  • The phoneType field of "111-444-5555" has been populated since the AfterGenerate.POPULATE_NULLS was specified.
  • The collection has been shuffled since the shuffle() was specified.
Since:
2.0.0
See Also:

  • Method Details

    • empty

      public static CollectionHint empty()
      Returns an empty hint containing default values.
      Returns:
      empty hint
      Since:
      2.0.0

    • generateElements

      public int generateElements()
      Indicates the number of elements the engine should generate and insert into the collection.
      Returns:
      number of elements to generate
      Since:
      2.0.0

    • nullableElements

      public boolean nullableElements()
      Indicates whether elements can be null.
      Returns:
      true if elements are nullable, false otherwise
      Since:
      2.0.0

    • shuffle

      public boolean shuffle()
      Indicates whether collection elements should be shuffled.
      Returns:
      true if elements should be shuffled, false otherwise
      Since:
      2.0.0

    • unique

      public boolean unique()
      Indicates whether collection should contain unique elements.
      Returns:
      true if elements should be unique, false otherwise
      Since:
      2.8.0

    • withElements

      public <T> List<T> withElements()
      Returns additional elements provided by the generator to the engine that are to be inserted into the collection.
      Type Parameters:
      T - element type
      Returns:
      specific elements to be inserted into a collection
      Since:
      2.0.0

    • toString

      public String toString()
      Overrides:
      toString in class Object

    • builder

      public static CollectionHint.Builder builder()