Package org.instancio

Interface InstancioApi<T>

Type Parameters:
T - type being created
All Known Subinterfaces:
InstancioOfClassApi<T>
All Known Implementing Classes:
ClassInstancioApiImpl, InstancioApiImpl
public interface InstancioApi<T>
Instancio API for generating instances of a class populated with random data.

  • Method Details

    • create

      T create()
      Creates a new instance of a class and populates it with data.

      Example: 

      
     Person person = Instancio.of(Person.class).create();

      The returned object will have all its fields populated with random data, including collection and array fields.

      Returns:
      a fully populated object

    • toModel

      Model<T> toModel()
      Creates a model containing all the information for populating a class.

      The model can be useful when class population needs to be customised and the customisations need to be re-used in different parts of the code.

      Example: 

      
     Model<Person> personModel = Instancio.of(Person.class)
             .supply(field("fullName"), () -> "Jane Doe")
             .toModel();

     // Re-use the model to create instances of Person class
     // without duplicating the model's details
     Person person = Instancio.of(personModel).create();

      Since the internal data of the model is not part of the public API, the Model interface does not contain any methods.

      Returns:
      a model containing all the details

    • ignore

      InstancioApi<T> ignore(Binding target)
      Specifies that a class or field should be ignored.

      Example: 

      
     Person person = Instancio.of(Person.class)
             .ignore(field("pets"))  // Person.pets field
             .ignore(field(Address.class, "phoneNumbers")) // Address.phoneNumbers field
             .ignore(allStrings())
             .create();

      will create a fully populated person, but will ignore the address field and all string fields.

      Parameters:
      target - to ignore
      Returns:
      API builder reference

    • withNullable

      InstancioApi<T> withNullable(Binding target)
      Specifies that a field or class is nullable. By default, Instancio assigns non-null values. If marked as nullable, Instancio will randomly assign either a null or non-null value to fields of this type.

      Example: 

      
     Person person = Instancio.of(Person.class)
             .withNullable(allStrings())
             .withNullable(field(Address.class))
             .create();
      Parameters:
      target - that is nullable
      Returns:
      API builder reference

    • supply

      <V> InstancioApi<T> supply(Binding target, Supplier<V> supplier)
      Supplies a non-random value for a field or class using a Supplier.

      Example: 

      
     Person person = Instancio.of(Person.class)
             .supply(all(LocalDateTime.class), () -> LocalDateTime.now()) // set all dates to current time
             .supply(field("fullName"), () -> "Homer Simpson") // set Person.fullName
             .supply(field(Address.class, "phoneNumbers"), () -> List.of( // set Address.phoneNumbers
                 new PhoneNumber("+1", "123-45-67"),
                 new PhoneNumber("+1", "345-67-89")))
             .create();

      Note: Instancio will not modify the supplied instance in any way. If the PhoneNumber class has other fields, they will be ignored.

      For supplying random values, see supply(Binding, Generator).

      Type Parameters:
      V - type of the value to generate
      Parameters:
      target - binding
      supplier - for the target's value
      Returns:
      API builder reference
      See Also:

    • supply

      <V> InstancioApi<T> supply(Binding target, Generator<V> generator)
      Supplies a randomised value for a field or class using a custom Generator.

      Example: 

      
     Person person = Instancio.of(Person.class)
             .supply(field(Address.class, "phoneNumbers"), random -> List.of(
                     // Generate phone numbers with a random country code, either US or Mexico
                     new PhoneNumber(random.from("+1", "+52"), "123-55-66"),
                     new PhoneNumber(random.from("+1", "+52"), "123-77-88")))
             .create();

      Note: Instancio will not modify the supplied instance in any way. If the PhoneNumber class has other fields, they will be ignored.

      Type Parameters:
      V - type of the value to generate
      Parameters:
      target - binding
      generator - for supplying the target's value
      Returns:
      API builder reference

    • generate

      <V, S extends GeneratorSpec<V>> InstancioApi<T> generate(Binding target, Function<Generators,S> gen)
      Generates a random value for a field or class using a built-in generator.

      Example: 

      
     Person person = Instancio.of(Person.class)
             .generate(field("age"), gen -> gen.ints().min(18).max(100))
             .generate(field("name"), gen -> gen.string().min(5).allowEmpty())
             .generate(field(Address.class, "phoneNumbers"), gen -> gen.collection().minSize(5))
             .generate(field(Address.class, "city"), gen -> gen.oneOf("Burnaby", "Vancouver", "Richmond"))
             .create();
      Type Parameters:
      V - type of the value to generate
      S - generator spec type
      Parameters:
      target - binding
      gen - provider of built-in generators
      Returns:
      API builder reference

    • onComplete

      <V> InstancioApi<T> onComplete(Binding target, OnCompleteCallback<V> callback)
      A callback that gets invoked after an object has been fully populated.

      Example: 

      
     // Sets countryCode field on all instances of Phone to the specified value
     Person person = Instancio.of(Person.class)
             .onComplete(all(Phone.class), (Phone phone) -> phone.setCountryCode("+1"))
             .create();
      Type Parameters:
      V - type of object handled by the callback
      Parameters:
      target - binding
      callback - to invoke after object has been populated
      Returns:
      API builder reference

    • map

      InstancioApi<T> map(Binding target, Class<?> subtype)
      Maps target field or class to the given subtype.

      For example, by default Instancio will assign an ArrayList to a List field. If an alternative implementation is required, this method allows to specify it: 

      
     Person person = Instancio.of(Person.class)
             .map(all(List.class), Vector.class)
             .create();

      will assign all Lists to Vectors.

      Parameters:
      target - binding
      subtype - of the type target binding
      Returns:
      API builder reference

    • withSettings

      InstancioApi<T> withSettings(Settings settings)
      Override default settings for generated values. Settings include collection sizes, string lengths, numeric ranges, etc.
      Parameters:
      settings - to use
      Returns:
      API builder reference

    • withSeed

      InstancioApi<T> withSeed(int seed)
      Set the seed value for the random number generator. If seed is not specified, a random seed will be used. Specifying a seed is useful for reproducing test results. By specifying the seed value, the same random data will be generated again.

      Example: 

      
     // Generates a different UUID each time
     UUID result = Instancio.of(UUID.class).create();

     // Generates the same UUID
     UUID result = Instancio.of(UUID.class)
             .withSeed(1234)
             .create();
      Parameters:
      seed - for the random number generator
      Returns:
      API builder reference