Package org.instancio
Class Instancio
java.lang.Object
org.instancio.Instancio
Instancio API for creating instances of a class.
Allow
Default behaviour is to populate every field with a non-null, random value.
Specifying nullable will randomly generate either a Creating instances of a class from a
Class specifications can also be saved as a Option 1: using
Option 2: using a
Usage
Create and populate an instance of a class
Returns an object fully populated with random data with nonull
values.
Person person = Instancio.of(Person.class).create();
Specify custom value generators for fields
Returns an object populated with random data except the specified fields using custom generators.
Person person = Instancio.of(Person.class)
.supply(field("fullName"), () -> "Homer Simpson") // Person.name
.supply(field(Address.class, "phoneNumber"), () -> new PhoneNumber("+1", "123-45-67"))
.create();
Allow null
values to be generated
Default behaviour is to populate every field with a non-null, random value.
Specifying nullable will randomly generate either a null
value or an actual value.
Person person = Instancio.of(Person.class)
.withNullable(field("gender")) // Person.gender is nullable
.withNullable(field(Address.class, "street")) // Address.street is nullable
.withNullable(all(Date.class)) // all dates are nullable
.create();
Ignore certain fields or classes
Ignored field will not be populated. Ignored fields values will benull
(unless they have a default value).
Person person = Instancio.of(Person.class)
.ignore(field("age")) // Person.age will be ignored
.ignore(field(Address.class, "city")) // Address.city will be ignored
.ignore(all(Date.class)) // all dates will be ignored
.create();
Creating instances of a class from a Model
Class specifications can also be saved as a Model
using the toModel()
method.
Then instances of a class can be generated from the model. Models can be useful for:
- reducing code duplication by re-using the same model in different parts of the code
- acting as a prototype for creating specialised instances of a class by overriding model specifications
// Create a model
Model<Person> simpsons = Instancio.of(Person.class)
.supply(all(Address.class), () -> new Address("742 Evergreen Terrace", "Springfield", "US"))
.supply(field("pets"), () -> 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.of(simpsons).create();
// Use the model but override the name field generator
Person homer = Instancio.of(simpsons).supply(field("name"), () -> "Homer").create();
Person marge = Instancio.of(simpsons).supply(field("name"), () -> "Marge").create();
// A model can also used to create another model.
// This snippet overrides the original model to include a new pet.
Model<Person> withNewPet = Instancio.of(simpsons)
.supply(field("pets"), () -> 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 ways to create generic class instances.Option 1: using withTypeParameters
to specify generic type arguments
List<Person> person = Instancio.of(List.class).withTypeParameters(Person.class).create();
This will create a list of persons however it will generate an "unchecked assignment" warning.
Option 2: using a TypeToken
List<Person> person = Instancio.of(new TypeToken<List<Person>>() {}).create(); // note the empty '{}' braces
This will not generate a warning, though the syntax is slightly more awkward.
-
Method Summary
Modifier and TypeMethodDescriptionstatic <T> T
Creates a fully-populated instance of given class.static <T> T
Creates a populated instance of a class represented by the given model.static <T> T
create
(TypeTokenSupplier<T> typeToken) Creates a fully-populated instance of type specified in the type token.static <T> InstancioOfClassApi<T>
Builder version ofcreate(Class)
that allows customisation of generated values.static <T> InstancioApi<T>
Builder version ofcreate(Model)
that allows overriding of generation parameters of an existing model.static <T> InstancioApi<T>
of
(TypeTokenSupplier<T> typeToken) Builder version ofcreate(TypeTokenSupplier)
that allows customisation of generated values.
-
Method Details
-
create
Creates a fully-populated instance of given class.- Type Parameters:
T
- type- Parameters:
klass
- to create- Returns:
- a fully-populated instance
-
create
Creates a fully-populated instance of type specified in the type token. This method can be used to create generic classes.Example:
List<Person> persons = Instancio.of(new TypeToken<List<Person>>(){}).create()
- Type Parameters:
T
- type- Parameters:
typeToken
- containing type to create- Returns:
- a fully-populated instance
-
create
Creates a populated instance of a class represented by the given model.See the
Model
class on how to create models.- Type Parameters:
T
- type- Parameters:
model
- specifying generation parameters of the object to create- Returns:
- a populated instance
- See Also:
-
of
Builder version ofcreate(Class)
that allows customisation of generated values.Person person = Instancio.of(Person.class) .generate(allInts(), gen -> gen.ints().min(1).max(99)) .supply(all(Address.class), () -> new Address("742 Evergreen Terrace", "Springfield", "US")) .supply(field("pets"), () -> List.of( new Pet(PetType.CAT, "Snowball"), new Pet(PetType.DOG, "Santa's Little Helper"))) .create();
- Type Parameters:
T
- type- Parameters:
klass
- to create- Returns:
- API builder reference
-
of
Builder version ofcreate(TypeTokenSupplier)
that allows customisation of generated values.List<Person> persons = Instancio.of(new TypeToken<List<Person>>(){}) .generate(allInts(), gen -> gen.ints().min(1).max(99)) .supply(all(Address.class), () -> new Address("742 Evergreen Terrace", "Springfield", "US")) .supply(field("pets"), () -> List.of( new Pet(PetType.CAT, "Snowball"), new Pet(PetType.DOG, "Santa's Little Helper"))) .create();
- Type Parameters:
T
- type- Parameters:
typeToken
- specifying details of type being created- Returns:
- API builder reference
-
of
Builder version ofcreate(Model)
that allows overriding of generation parameters of an existing model.Model<Person> personModel = Instancio.of(Person.class) .generate(allInts(), gen -> gen.ints().min(1).max(99)) .supply(all(Address.class), () -> new Address("742 Evergreen Terrace", "Springfield", "US")) .supply(field("pets"), () -> List.of( new Pet(PetType.CAT, "Snowball"), new Pet(PetType.DOG, "Santa's Little Helper"))) .toModel(); // Use the existing model and add/override generation parameters Person simpsonKid = Instancio.of(personModel) .generate(field("fullName"), gen -> gen.oneOf("Lisa Simpson", "Bart Simpson")) .create();
- Type Parameters:
T
- type- Parameters:
model
- specifying generation parameters of the object to create- Returns:
- API builder reference
-