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 no null 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 be null (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.

Since:

1.0.1

Method Summary

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 of create(Class) that allows customisation of generated values.
static <T> InstancioApi<T>	of(Model<T> model)	Builder version of create(Model) that allows overriding of generation parameters of an existing model.
static <T> InstancioApi<T>	of(TypeTokenSupplier<T> typeToken)	Builder version of create(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.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

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 of create(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 of create(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 of create(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