Package org.instancio.internal

Class InstancioApiImpl<T>

java.lang.Object

org.instancio.internal.InstancioApiImpl<T>

All Implemented Interfaces:

InstancioApi<T>

Direct Known Subclasses:

ClassInstancioApiImpl

public class InstancioApiImpl<T>
extends Object
implements InstancioApi<T>

Constructor Summary

Constructors

Constructor	Description
InstancioApiImpl(Class<T> klass)
InstancioApiImpl(Model<T> model)
InstancioApiImpl(TypeTokenSupplier<T> typeToken)

Method Summary

Modifier and Type	Method	Description
protected void	addTypeParameters(Class<?>... type)
T	create()	Creates a new instance of a class and populates it with data.
<V,S extends GeneratorSpec<V>> InstancioApi<T>	generate(SelectorGroup target, Function<Generators,S> gen)	Generates a random value for a field or class using a built-in generator.
InstancioApi<T>	ignore(SelectorGroup selectorGroup)	Specifies that a class or field should be ignored.
InstancioApi<T>	map(SelectorGroup selectorGroup, Class<?> subtype)	Maps target field or class to the given subtype.
<V> InstancioApi<T>	onComplete(SelectorGroup target, OnCompleteCallback<V> callback)	A callback that gets invoked after an object has been fully populated.
Stream<T>	stream()	Creates an infinite stream of distinct, fully populated objects.
<V> InstancioApi<T>	supply(SelectorGroup selectorGroup, Supplier<V> supplier)	Supplies a non-random value for a field or class using a Supplier.
<V> InstancioApi<T>	supply(SelectorGroup selectorGroup, Generator<V> generator)	Supplies a randomised value for a field or class using a custom Generator.
Model<T>	toModel()	Creates a model containing all the information for populating a class.
InstancioApi<T>	withNullable(SelectorGroup target)	Specifies that a field or class is nullable.
InstancioApi<T>	withSeed(int seed)	Set the seed value for the random number generator.
InstancioApi<T>	withSettings(Settings settings)	Override default settings for generated values.

Methods inherited from class java.lang.Object

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

Constructor Detail

InstancioApiImpl

public InstancioApiImpl(Class<T> klass)

InstancioApiImpl

public InstancioApiImpl(TypeTokenSupplier<T> typeToken)

InstancioApiImpl

public InstancioApiImpl(Model<T> model)

Method Detail

addTypeParameters

protected void addTypeParameters(Class<?>... type)

ignore

public InstancioApi<T> ignore(SelectorGroup selectorGroup)

Description copied from interface: InstancioApi

Specifies that a class or field should be ignored.

Example:

     Person person = Instancio.of(Person.class)
             .ignore(field("pets"))  // Person.pets field
             .ignore(field(Address.class, "phoneNumbers")) // Address.phoneNumbers field
             .ignore(allStrings())
             .create();
 

will create a fully populated person, but will ignore the address field and all string fields.

Specified by:

ignore in interface InstancioApi<T>

Parameters:

selectorGroup - for fields and/or classes this method should be applied to

Returns:

API builder reference

withNullable

public InstancioApi<T> withNullable(SelectorGroup target)

Description copied from interface: InstancioApi

Specifies that a field or class is nullable. By default, Instancio assigns non-null values. If marked as nullable, Instancio will randomly assign either a null or non-null value to fields of this type.

Example:

     Person person = Instancio.of(Person.class)
             .withNullable(allStrings())
             .withNullable(field(Address.class))
             .create();
 

Specified by:

withNullable in interface InstancioApi<T>

Parameters:

target - for fields and/or classes this method should be applied to

Returns:

API builder reference

supply

public <V> InstancioApi<T> supply(SelectorGroup selectorGroup,
                                  Generator<V> generator)

Description copied from interface: InstancioApi

Supplies a randomised value for a field or class using a custom Generator.

Example:

     Person person = Instancio.of(Person.class)
             .supply(field(Address.class, "phoneNumbers"), random -> List.of(
                     // Generate phone numbers with a random country code, either US or Mexico
                     new PhoneNumber(random.from("+1", "+52"), "123-55-66"),
                     new PhoneNumber(random.from("+1", "+52"), "123-77-88")))
             .create();
 

Note: Instancio will not modify the supplied instance in any way. If the PhoneNumber class has other fields, they will be ignored.

Specified by:

supply in interface InstancioApi<T>

Type Parameters:

V - type of the value to generate

Parameters:

selectorGroup - for fields and/or classes this method should be applied to

generator - that will provide the values

Returns:

API builder reference

supply

public <V> InstancioApi<T> supply(SelectorGroup selectorGroup,
                                  Supplier<V> supplier)

Description copied from interface: InstancioApi

Supplies a non-random value for a field or class using a Supplier.

Example:

     Person person = Instancio.of(Person.class)
             .supply(all(LocalDateTime.class), () -> LocalDateTime.now()) // set all dates to current time
             .supply(field("fullName"), () -> "Homer Simpson") // set Person.fullName
             .supply(field(Address.class, "phoneNumbers"), () -> List.of( // set Address.phoneNumbers
                 new PhoneNumber("+1", "123-45-67"),
                 new PhoneNumber("+1", "345-67-89")))
             .create();
 

Note: Instancio will not modify the supplied instance in any way. If the PhoneNumber class has other fields, they will be ignored.

For supplying random values, see InstancioApi.supply(SelectorGroup, Generator).

Specified by:

supply in interface InstancioApi<T>

Type Parameters:

V - type of the value to generate

Parameters:

selectorGroup - for fields and/or classes this method should be applied to

supplier - providing the value for given selectors

Returns:

API builder reference

See Also:

InstancioApi.supply(SelectorGroup, Generator)

generate

public <V,S extends GeneratorSpec<V>> InstancioApi<T> generate(SelectorGroup target,
                                                                     Function<Generators,S> gen)

Description copied from interface: InstancioApi

Generates a random value for a field or class using a built-in generator.

Example:

     Person person = Instancio.of(Person.class)
             .generate(field("age"), gen -> gen.ints().min(18).max(100))
             .generate(field("name"), gen -> gen.string().min(5).allowEmpty())
             .generate(field(Address.class, "phoneNumbers"), gen -> gen.collection().minSize(5))
             .generate(field(Address.class, "city"), gen -> gen.oneOf("Burnaby", "Vancouver", "Richmond"))
             .create();
 

Specified by:

generate in interface InstancioApi<T>

Type Parameters:

V - type of the value to generate

S - generator spec type

Parameters:

target - for fields and/or classes this method should be applied to

gen - provider of built-in generators

Returns:

API builder reference

onComplete

public <V> InstancioApi<T> onComplete(SelectorGroup target,
                                      OnCompleteCallback<V> callback)

Description copied from interface: InstancioApi

A callback that gets invoked after an object has been fully populated.

Example:

     // Sets countryCode field on all instances of Phone to the specified value
     Person person = Instancio.of(Person.class)
             .onComplete(all(Phone.class), (Phone phone) -> phone.setCountryCode("+1"))
             .create();
 

Specified by:

onComplete in interface InstancioApi<T>

Type Parameters:

V - type of object handled by the callback

Parameters:

target - for fields and/or classes this method should be applied to

callback - to invoke after object has been populated

Returns:

API builder reference

map

public InstancioApi<T> map(SelectorGroup selectorGroup,
                           Class<?> subtype)

Description copied from interface: InstancioApi

Maps target field or class to the given subtype. This can be used in the following cases:

1. to specify an implementation for interfaces or abstract classes
2. to override default implementations used by Instancio

Specify an implementation for an abstract type

When Instancio encounters an interface or an abstract type it is not aware of (for example, that is not part of the JDK), it will not be able to instantiate it. This method can be used to specify an implementation to use in such cases. For example:

     WidgetContainer container = Instancio.of(WidgetContainer.class)
             .map(all(AbstractWidget.class), ConcreteWidget.class)
             .create();
 

Override default implementations

By default, Instancio uses certain defaults for collection classes, for example ArrayList for List. If an alternative implementation is required, this method allows to specify it:

     Person person = Instancio.of(Person.class)
             .map(all(List.class), LinkedList.class)
             .create();
 

will use the LinkedList implementation for all Lists.

Specified by:

map in interface InstancioApi<T>

Parameters:

selectorGroup - for fields and/or classes this method should be applied to

subtype - to map the selectors to

Returns:

API builder reference

withSettings

public InstancioApi<T> withSettings(Settings settings)

Description copied from interface: InstancioApi

Override default settings for generated values. Settings include collection sizes, string lengths, numeric ranges, etc.

Specified by:

withSettings in interface InstancioApi<T>

Parameters:

settings - to use

Returns:

API builder reference

withSeed

public InstancioApi<T> withSeed(int seed)

Description copied from interface: InstancioApi

Set the seed value for the random number generator. If seed is not specified, a random seed will be used. Specifying a seed is useful for reproducing test results. By specifying the seed value, the same random data will be generated again.

Example:

     // Generates a different UUID each time
     UUID result = Instancio.of(UUID.class).create();

     // Generates the same UUID
     UUID result = Instancio.of(UUID.class)
             .withSeed(1234)
             .create();
 

Specified by:

withSeed in interface InstancioApi<T>

Parameters:

seed - for the random number generator

Returns:

API builder reference

toModel

public Model<T> toModel()

Description copied from interface: InstancioApi

Creates a model containing all the information for populating a class.

The model can be useful when class population needs to be customised and the customisations need to be re-used in different parts of the code.

Example:

     Model<Person> personModel = Instancio.of(Person.class)
             .supply(field("fullName"), () -> "Jane Doe")
             .toModel();

     // Re-use the model to create instances of Person class
     // without duplicating the model's details
     Person person = Instancio.of(personModel).create();
 

Since the internal data of the model is not part of the public API, the Model interface does not contain any methods.

Specified by:

toModel in interface InstancioApi<T>

Returns:

a model containing all the details

create

public T create()

Description copied from interface: InstancioApi

Creates a new instance of a class and populates it with data.

Example:

     Person person = Instancio.of(Person.class).create();
 

The returned object will have all its fields populated with random data, including collection and array fields.

Specified by:

create in interface InstancioApi<T>

Returns:

a fully populated object

stream

public Stream<T> stream()

Description copied from interface: InstancioApi

Creates an infinite stream of distinct, fully populated objects.

Example:

     List<Person> persons = Instancio.of(Person.class)
         .stream()
         .limit(5)
         .collect(Collectors.toList());
 

Specified by:

stream in interface InstancioApi<T>

Returns:

an infinite stream of distinct, populated objects