Package org.instancio.generator.hints

Class MapHint

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

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

Sample use case

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

This can be achieved as follows: 


 class PhonesGenerator implements Generator<Map<Long, Phone>> {

     @Override
     public Map<Long, Phone> generate(Random random) {
         Map<Long, Phone> map = new HashMap<>();
         map.put(1L, Phone.builder().number("111-222-3333").phoneType(PhoneType.CELL).build());
         map.put(2L, Phone.builder().number("111-444-5555").build()); // phoneType is null, but will be populated
         return map;
     }

     @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(MapHint.builder()
                          // number of additional entries to be generated and added to the map by the engine
                         .generateEntries(3)
                         .build())
                 .build();
     }
 }

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

 Map<Long, Phone> map = person.getPhones();

 // Expected results:
 assertThat(map).hasSize(5);

 assertThat(map).extractingByKey(1L)
         .matches(p -> p.getNumber().equals("111-222-3333") && p.getPhoneType() == PhoneType.CELL);

 assertThat(map).extractingByKey(2L)
         .matches(p -> p.getNumber().equals("111-444-5555") && p.getPhoneType() != null);

Summary of results:

  • The generated map 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.
Since:
2.0.0
See Also:

  • Nested Class Summary

    Nested Classes
    Modifier and Type
    Class
    Description
    static final class 
    MapHint.Builder
    Builder class for this hint.

  • Method Summary

    Modifier and Type
    Method
    Description
    static MapHint.Builder
    builder()
    Returns a builder for this hint type.
    static MapHint
    empty()
    Returns an empty hint containing default values.
    int
    generateEntries()
    Indicates the number of entries the engine should generate and insert into the map.
    boolean
    nullableMapKeys()
    Indicates whether map keys can be null.
    boolean
    nullableMapValues()
    Indicates whether map values can be null.
    String
    toString()
     
    <K, V> Map<K,V>
    withEntries()
    Returns additional entries provided by the generator to the engine that are to be inserted into the map.
    <K> List<K>
    withKeys()
    Returns keys provided by the generator to the engine that are to be inserted into the map.

    Methods inherited from class java.lang.Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

    Methods inherited from interface org.instancio.generator.Hint

    type

  • Method Details

    • empty

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

    • generateEntries

      public int generateEntries()
      Indicates the number of entries the engine should generate and insert into the map.
      Returns:
      number of entries to generate
      Since:
      2.0.0

    • nullableMapKeys

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

    • nullableMapValues

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

    • withEntries

      public <K, V> Map<K,V> withEntries()
      Returns additional entries provided by the generator to the engine that are to be inserted into the map.
      Type Parameters:
      K - key type
      V - value type
      Returns:
      specific entries to be inserted into the map
      Since:
      2.0.0

    • withKeys

      public <K> List<K> withKeys()
      Returns keys provided by the generator to the engine that are to be inserted into the map.
      Type Parameters:
      K - key type
      Returns:
      keys to be inserted into the map
      Since:
      2.0.0

    • toString

      public String toString()
      Overrides:
      toString in class Object

    • builder

      public static MapHint.Builder builder()
      Returns a builder for this hint type.
      Returns:
      hint builder