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 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
Default behaviour is to populate every field with a non-null, random value. Specifying nullable will randomly generate either anull
values to be generatednull
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
Class specifications can also be saved as aModel
Model
using thetoModel()
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 argumentsList<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.
- Since:
- 1.0.1
-
-
Method Summary
All Methods Static Methods Concrete Methods Modifier and Type Method Description static <T> T
create(Class<T> klass)
Creates a fully-populated instance of given class.static <T> T
create(Model<T> model)
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>
of(Class<T> klass)
Builder version ofcreate(Class)
that allows customisation of generated values.static <T> InstancioApi<T>
of(Model<T> model)
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> Stream<T>
stream(Class<T> klass)
Creates an infinite stream of distinct, fully populated instances of given class.static <T> Stream<T>
stream(TypeTokenSupplier<T> typeToken)
Creates an infinite stream of distinct, fully populated instances of type specified in the type token.
-
-
-
Method Detail
-
create
public static <T> T create(Class<T> klass)
Creates a fully-populated instance of given class.- Type Parameters:
T
- type- Parameters:
klass
- to create- Returns:
- a fully-populated instance
- Since:
- 1.0.1
-
stream
public static <T> Stream<T> stream(Class<T> klass)
Creates an infinite stream of distinct, fully populated instances of given class.Example:
List<Person> persons = Instancio.stream(Person.class) .limit(5) .collect(Collectors.toList());
- Type Parameters:
T
- type- Parameters:
klass
- to create- Returns:
- an infinite stream of distinct, fully populated instances
- Since:
- 1.1.9
-
create
public static <T> T create(TypeTokenSupplier<T> typeToken)
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
-
stream
public static <T> Stream<T> stream(TypeTokenSupplier<T> typeToken)
Creates an infinite stream of distinct, fully populated instances of type specified in the type token.Example:
List<Pair<Integer, String>> pairs = Instancio.stream(new TypeToken<Pair<Integer, String>>() {}) .limit(5) .collect(Collectors.toList());
- Type Parameters:
T
- type- Parameters:
typeToken
- containing type to create- Returns:
- an infinite stream of distinct, fully populated instances
- Since:
- 1.1.9
-
create
public static <T> T create(Model<T> model)
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:
Model
-
of
public static <T> InstancioOfClassApi<T> of(Class<T> klass)
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
public static <T> InstancioApi<T> of(TypeTokenSupplier<T> typeToken)
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
public static <T> InstancioApi<T> of(Model<T> model)
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
-
-