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:

• InstancioApi
• Select

Method Summary

Modifier and Type	Method	Description
static <T> T	create(Class<T> type)	Creates an instance of the specified class.
static <T> T	create(Model<T> model)	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> InstancioOfClassApi<T>	of(Class<T> type)	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> InstancioOfCollectionApi<List<T>>	ofList(Class<T> elementType)	Builder API for generating a List that allows customisation of generated values.
static <T> InstancioOfCollectionApi<List<T>>	ofList(Model<T> elementModel)	Builder API for generating a List using the specified model for list elements.
static <K, V> InstancioOfCollectionApi<Map<K,V>>	ofMap(Class<K> keyType, Class<V> valueType)	Builder API for generating a Map that allowss customisation of generated values.
static <T> InstancioOfCollectionApi<Set<T>>	ofSet(Class<T> elementType)	Builder API for generating a Set that allows customisation of generated values.
static <T> InstancioOfCollectionApi<Set<T>>	ofSet(Model<T> elementModel)	Builder API for generating a Set using the specified model for list elements.
static <T> Stream<T>	stream(Class<T> type)	Creates an infinite stream of instances of the specified class.
static <T> Stream<T>	stream(Model<T> model)	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.

Methods inherited from class java.lang.Object

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

Method Details

create

public static <T> T create(Class<T> type)

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

stream

public static <T> Stream<T> stream(Class<T> type)

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

public static <T> T create(TypeTokenSupplier<T> typeToken)

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

public static <T> Stream<T> stream(TypeTokenSupplier<T> typeToken)

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

public static <T> T create(Model<T> model)

Creates an object populated using the given model. If the object needs to be customised, use the of(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:

• InstancioApi.toModel()
• of(Model)
• stream(Model)

stream

public static <T> Stream<T> stream(Model<T> model)

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:

• create(Model)
• of(Model)

of

public static <T> InstancioOfClassApi<T> of(Class<T> type)

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 - the type of object

Parameters:

type - 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 - the type of object

Parameters:

typeToken - specifying the type to create

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 - the type of object

Parameters:

model - specifying generation parameters of the object to create

Returns:

API builder reference

ofList

public static <T> InstancioOfCollectionApi<List<T>> ofList(Class<T> elementType)

Builder API for generating a List that allows customisation of generated values.

Type Parameters:

T - element type

Parameters:

elementType - class to generate as list elements

Returns:

API builder reference

Since:

2.0.0

ofList

public static <T> InstancioOfCollectionApi<List<T>> ofList(Model<T> elementModel)

Builder API for generating a List 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

public static <T> InstancioOfCollectionApi<Set<T>> ofSet(Class<T> elementType)

Builder API for generating a Set 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

public static <T> InstancioOfCollectionApi<Set<T>> ofSet(Model<T> elementModel)

Builder API for generating a Set 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

public static <K,
V>
InstancioOfCollectionApi<Map<K,V>> ofMap(Class<K> keyType,
 Class<V> valueType)

Builder API for generating a Map that allowss customisation of generated values.

Type Parameters:

K - key type

V - value type

Parameters:

keyType - class to generate as map keys

valueType - class to generate as map values

Returns:

API builder reference

Since:

2.0.0