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 Summary

All Methods Instance Methods Abstract Methods
Modifier and Type	Method	Description
`T`	`create()`	Creates a new instance of a class and populates it with data.
`<V,S extends GeneratorSpec<V>> InstancioApi<T>`	`generate(Binding target, Function<Generators,S> gen)`	Supplies a random value for a field or class using a built-in generator.
`InstancioApi<T>`	`ignore(Binding target)`	Specifies that a class or field should be ignored.
`InstancioApi<T>`	`map(Class<?> baseClass, Class<?> subClass)`	Maps an interface or base class to the given subclass.
`<V> InstancioApi<T>`	`onComplete(Binding target, OnCompleteCallback<V> callback)`	A callback that gets invoked after an object has been fully populated.
`<V> InstancioApi<T>`	`supply(Binding target, Generator<V> generator)`	Supplies a value for a field or class using a custom generator.
`Model<T>`	`toModel()`	Creates a model containing all the information for populating a class.
`InstancioApi<T>`	`withNullable(Binding target)`	Specifies that a field or class is nullable.
`InstancioApi<T>`	`withSeed(int seed)`	Set the seed value for the random number generator.
`InstancioApi<T>`	`withSettings(Settings settings)`	Override default settings for generated values.

Method Detail

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, this 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,
                           Generator<V> generator)

Supplies a value for a field or class using a custom generator.

Examples.


     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: when a custom generator is supplied for a complex type like PhoneNumber in the above example, Instancio will not modify the created 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)

Supplies 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(Class<?> baseClass,
                    Class<?> subClass)
```
Maps an interface or base class to the given subclass. The subClass must either extend or implement the baseClass.
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(List.class, Vector.class)
             .create();
 
```
will assign all Lists to Vectors.
Parameters:

baseClass - interface or base class

subClass - subtype of the baseClass

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

Interface InstancioApi<T>

Method Summary

Method Detail

create

toModel

ignore

withNullable

supply

generate

onComplete

map

withSettings

withSeed