Class Instancio
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 benull
(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:
-
Method Summary
Modifier and TypeMethodDescriptionstatic <T> T
Creates an instance of the specified class.static <T> T
Creates an object populated using the given model.static <T> T
create
(TypeTokenSupplier<T> typeToken) Creates an object of type specified by the type token.static <T> List
<T> createList
(Class<T> elementType) Creates aList
of random size.static <K,
V> Map <K, V> Creates aMap
of random size.static <T> Set
<T> Creates aSet
of random size.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.static <T> CartesianProductApi
<T> ofCartesianProduct
(Class<T> type) Generates the Cartesian product based on the values specified via thewith()
method.static <T> CartesianProductApi
<T> ofCartesianProduct
(Model<T> model) Generates the Cartesian product based on the values specified via thewith()
method.static <T> CartesianProductApi
<T> ofCartesianProduct
(TypeTokenSupplier<T> typeToken) Generates the Cartesian product based on the values specified via thewith()
method.static <T> InstancioOfCollectionApi
<List<T>> Builder API for generating aList
that allows customising generated values.static <T> InstancioOfCollectionApi
<List<T>> Builder API for generating aList
using the specified model for list elements.static <T> InstancioOfCollectionApi
<List<T>> ofList
(TypeTokenSupplier<T> elementTypeToken) Builder API for generating aList
using a type token.static <K,
V> InstancioOfCollectionApi <Map<K, V>> Builder API for generating aMap
that allowss customisation of generated values.static <K,
V> InstancioOfCollectionApi <Map<K, V>> ofMap
(TypeTokenSupplier<K> keyTypeToken, TypeTokenSupplier<V> valueTypeToken) Builder API for generating aMap
using type tokens.static <T> InstancioOfCollectionApi
<Set<T>> Builder API for generating aSet
that allows customisation of generated values.static <T> InstancioOfCollectionApi
<Set<T>> Builder API for generating aSet
using the specified model for list elements.static <T> InstancioOfCollectionApi
<Set<T>> ofSet
(TypeTokenSupplier<T> elementTypeToken) Builder API for generating aSet
using a type token.static <T> Stream
<T> Creates an infinite stream of instances of the specified class.static <T> Stream
<T> Creates an infinite stream of objects populated using the given model.static <T> Stream
<T> stream
(TypeTokenSupplier<T> typeToken) Creates an infinite stream of objects of type specified by the type token.
-
Method Details
-
create
Creates an instance of the specified class.- Type Parameters:
T
- the type of object- Parameters:
type
- to create- Returns:
- an object of the specified type
- Since:
- 1.0.1
-
createList
Creates aList
of random size.Unless configured otherwise, the generated size will be between
Keys.COLLECTION_MIN_SIZE
andKeys.COLLECTION_MAX_SIZE
, inclusive.To create a list of a specific size, use
ofList(Class)
.- Type Parameters:
T
- element type- Parameters:
elementType
- class to generate as list elements- Returns:
- API builder reference
- Since:
- 3.0.1
-
createSet
Creates aSet
of random size.Unless configured otherwise, the generated size will be between
Keys.COLLECTION_MIN_SIZE
andKeys.COLLECTION_MAX_SIZE
, inclusive.To create a
Set
of a specific size, useofSet(Class)
.- Type Parameters:
T
- element type- Parameters:
elementType
- class to generate as set elements- Returns:
- API builder reference
- Since:
- 3.0.1
-
createMap
Creates aMap
of random size.Unless configured otherwise, the generated size will be between
Keys.MAP_MIN_SIZE
andKeys.MAP_MAX_SIZE
, inclusive.To create a
Map
of a specific size, useofMap(Class, Class)
.- Type Parameters:
K
- key typeV
- value type- Parameters:
keyType
- class to generate as map keysvalueType
- class to generate as map values- Returns:
- API builder reference
- Since:
- 3.0.1
-
stream
Creates an infinite stream of instances of the specified class.Example:
List<Person> persons = Instancio.stream(Person.class) .limit(5) .collect(Collectors.toList());
- Type Parameters:
T
- the type of object- Parameters:
type
- to create- Returns:
- an infinite stream of objects of the specified type
- Since:
- 1.1.9
-
create
Creates an object of type specified by the type token. This method can be used for creating instances of generic types.Example:
Pair<UUID, Person> pair = Instancio.create(new TypeToken<Pair<UUID, Person>>(){});
- Type Parameters:
T
- the type of object- Parameters:
typeToken
- specifying the type to create- Returns:
- an object of the specified type
-
stream
Creates an infinite stream of objects of type specified by the type token. This method can be used for creating streams of generic types.Example:
List<Pair<Integer, String>> pairs = Instancio.stream(new TypeToken<Pair<Integer, String>>() {}) .limit(5) .collect(Collectors.toList());
- Type Parameters:
T
- the type of object- Parameters:
typeToken
- specifying the type to create- Returns:
- an infinite stream of objects of the specified type
- Since:
- 1.1.9
-
create
Creates an object populated using the given model. If the object needs to be customised, use theof(Model)
method.For an example of how to create a model, see
InstancioApi.toModel()
.- Type Parameters:
T
- the type of object- Parameters:
model
- a model that will be used as a template for creating the object- Returns:
- an object created based on the model
- See Also:
-
stream
Creates an infinite stream of objects populated using the given model.Example:
Model<Person> model = Instancio.of(Person.class) .ignore(field(Person::getId)) .generate(field(Person::dateOfBirth), gen -> gen.temporal().localDate().past()) .toModel(); List<Person> persons = Instancio.stream(model) .limit(5) .collect(Collectors.toList());
- Type Parameters:
T
- the type of object- Parameters:
model
- that will be used to generate the objects- Returns:
- an infinite stream of objects created based on the model
- Since:
- 2.4.0
- 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
- the type of object- Parameters:
type
- 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
- the type of object- Parameters:
typeToken
- specifying the type to create- 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
- the type of object- Parameters:
model
- specifying generation parameters of the object to create- Returns:
- API builder reference
-
ofCartesianProduct
Generates the Cartesian product based on the values specified via thewith()
method. The Cartesian product is returned as aList
in lexicographical order.Example:
record Widget(String type, int num) {} List<Widget> results = Instancio.ofCartesianProduct(Widget.class) .with(field(Widget::type), "FOO", "BAR", "BAZ") .with(field(Widget::num), 1, 2, 3) .list();
This will produce the following list of
Widget
objects:[Widget[type=FOO, num=1], Widget[type=FOO, num=2], Widget[type=FOO, num=3], Widget[type=BAR, num=1], Widget[type=BAR, num=2], Widget[type=BAR, num=3], Widget[type=BAZ, num=1], Widget[type=BAZ, num=2], Widget[type=BAZ, num=3]]
- Type Parameters:
T
- the type of object- Parameters:
type
- to create- Returns:
- API builder reference
- Since:
- 4.0.0
- See Also:
-
ofCartesianProduct
@ExperimentalApi public static <T> CartesianProductApi<T> ofCartesianProduct(TypeTokenSupplier<T> typeToken) Generates the Cartesian product based on the values specified via thewith()
method. The Cartesian product is returned as aList
in lexicographical order.See
ofCartesianProduct(Class)
for an example.- Type Parameters:
T
- the type of object- Parameters:
typeToken
- specifying the type to create- Returns:
- API builder reference
- Since:
- 4.0.0
- See Also:
-
ofCartesianProduct
Generates the Cartesian product based on the values specified via thewith()
method. The Cartesian product is returned as aList
in lexicographical order.See
ofCartesianProduct(Class)
for an example.- Type Parameters:
T
- the type of object- Parameters:
model
- specifying generation parameters of the object to create- Returns:
- API builder reference
- Since:
- 4.0.0
- See Also:
-
ofList
Builder API for generating aList
that allows customising generated values.- Type Parameters:
T
- element type- Parameters:
elementType
- class to generate as list elements- Returns:
- API builder reference
- Since:
- 2.0.0
-
ofList
Builder API for generating aList
using a type token.- Type Parameters:
T
- element type- Parameters:
elementTypeToken
- specifying the element type- Returns:
- API builder reference
- Since:
- 2.16.0
-
ofList
Builder API for generating aList
using the specified model for list elements.- Type Parameters:
T
- element type- Parameters:
elementModel
- a model for creating list elements- Returns:
- API builder reference
- Since:
- 2.5.0
-
ofSet
Builder API for generating aSet
that allows customisation of generated values.- Type Parameters:
T
- element type- Parameters:
elementType
- class to generate as set elements- Returns:
- API builder reference
- Since:
- 2.0.0
-
ofSet
Builder API for generating aSet
using a type token.- Type Parameters:
T
- element type- Parameters:
elementTypeToken
- specifying the element type- Returns:
- API builder reference
- Since:
- 2.16.0
-
ofSet
Builder API for generating aSet
using the specified model for list elements.- Type Parameters:
T
- element type- Parameters:
elementModel
- a model for creating set elements- Returns:
- API builder reference
- Since:
- 2.5.0
-
ofMap
Builder API for generating aMap
that allowss customisation of generated values.- Type Parameters:
K
- key typeV
- value type- Parameters:
keyType
- class to generate as map keysvalueType
- class to generate as map values- Returns:
- API builder reference
- Since:
- 2.0.0
-
ofMap
public static <K,V> InstancioOfCollectionApi<Map<K,V>> ofMap(TypeTokenSupplier<K> keyTypeToken, TypeTokenSupplier<V> valueTypeToken) Builder API for generating aMap
using type tokens.- Type Parameters:
K
- key typeV
- value type- Parameters:
keyTypeToken
- specifying the key typevalueTypeToken
- specifying the value type- Returns:
- API builder reference
- Since:
- 2.16.0
-