Package org.instancio

Class Instancio

java.lang.Object
org.instancio.Instancio
public final class Instancio extends Object
Instancio API for creating instances of a class.

Usage

Create and populate an instance of a class

Returns an object fully populated with random data with non-null values. 

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

Customise object's values

Returns an object populated with random data and some specified fields' values customised. 

 Person person = Instancio.of(Person.class)
     .set(field(Person::getFullName), "Homer Simpson")
     .supply(all(LocalDateTime.class), () -> LocalDateTime.now())
     .generate(field(Phone::getNumber), gen -> gen.text().pattern("(#d#d#d) #d#d#d-#d#d#d#d"))
     .create();

Allow null values to be generated

Default behaviour is to populate every field with a non-null value. Specifying nullable will randomly generate either null or non-null value. 

 Person person = Instancio.of(Person.class)
     .withNullable(field(Person::getDateOfBirth))
     .withNullable(all(Gender.class))
     .withNullable(allStrings())
     .create();

Ignore certain fields or classes

Ignored fields will not be populated. Their values will be null (unless they have a default value assigned). 

 Person person = Instancio.of(Person.class)
     .ignore(fields().named("id"))  // Person.id, Address.id, etc.
     .ignore(all(LocalDateTime.class))
     .create();

Creating instances of a class from a Model

Instancio builder API parameters can be saved as a Model object using the InstancioApi.toModel() method. Objects can then be generated based on the model. Models can be useful:
  • as a prototype for creating customised instances of a class by overriding model parameters
  • reducing code duplication by re-using the same model in different parts of the code

 // Create a model
 Model<Person> simpsons = Instancio.of(Person.class)
     .supply(all(Address.class), () -> new Address("742 Evergreen Terrace", "Springfield", "US"))
     .supply(field(Person::getPets), () -> List.of(
                  new Pet(PetType.CAT, "Snowball"),
                  new Pet(PetType.DOG, "Santa's Little Helper"))
     //... other specs
     .toModel();

 // Use the above model as is
 Person person = Instancio.create(simpsons);

 // Use the model but override the name
 Person homer = Instancio.of(simpsons).set(field(Person::getName), "Homer").create();
 Person marge = Instancio.of(simpsons).set(field(Person::getName), "Marge").create();

 // A model can also used to create another model.
 // This snippet creates a new model from the original model to include a new pet.
 Model<Person> withNewPet = Instancio.of(simpsons)
     .supply(field(Person::getPets), () -> List.of(
                  new Pet(PetType.PIG, "Plopper"),
                  new Pet(PetType.CAT, "Snowball"),
                  new Pet(PetType.DOG, "Santa's Little Helper"))
     .toModel();

Creating generic classes

There are two options for creating instances of a generic type.

Option 1: using a TypeToken


 Pair<Apple, Banana> pairOfFruits = Instancio.create(new TypeToken<Pair<Apple, Banana>>() {}); // note the empty '{}' braces

Option 2: using withTypeParameters to specify the type arguments


 Pair<Apple, Banana> pairOfFruits = Instancio.of(Pair.class)
     .withTypeParameters(Apple.class, Banana.class)
     .create();

The second approach allows specifying arbitrary type parameters at runtime, however using this method will produce an "unchecked assignment" warning.

Since:
1.0.1
See Also: