Package org.instancio

Class Assign

java.lang.Object

org.instancio.Assign

@ExperimentalApi
public final class Assign
extends Object

A collection of static factory methods for creating assignments.

Since:

3.0.0

See Also:

• Assignment
• InstancioApi.assign(Assignment...)

Method Summary

Modifier and Type	Method	Description
static <T> GivenOrigin	given(Class<T> origin)	Creates a conditional assignment for a given origin type.
static <T, R> GivenOrigin	given(GetMethodSelector<T,R> origin)	Creates a conditional assignment for a given origin method reference and one or more destination selectors.
static GivenOrigin	given(TargetSelector origin)	Creates a conditional for a given origin and one or more destination selectors.
static GivenOriginDestination	given(TargetSelector origin, TargetSelector destination)	Creates a conditional assigment for a given pair of origin and destination selectors.
static <T> ValueOf	valueOf(Class<T> target)	Creates an assignment for a given target type.
static <T, R> ValueOf	valueOf(GetMethodSelector<T,R> target)	Creates an assignment for a given target method reference.
static ValueOf	valueOf(TargetSelector target)	Creates an assignment builder with a given target selector.

Methods inherited from class java.lang.Object

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

Method Details

valueOf

@ExperimentalApi
public static ValueOf valueOf(TargetSelector target)

Creates an assignment builder with a given target selector. This builder provides two options:

1. Assign value directly to the target
2. Assign value of the target to another selector

1. Assign to target

The first option is to assign a value directly to the target using set(), supply(), or generate() methods.

Example:

 Assignment personName = Assign.valueOf(Person::getName).set("Homer Simpson");

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

This sets the Person.name field to "Homer Simpson". The above snippet is equivalent to:

 Person person = Instancio.of(Person.class)
     .set(Select.field(Person::getName), "Homer Simpson")
     .create();
 

The difference is that InstancioApi.assign(Assignment...) allows passing multiple assignments dynamically to the method since it accepts a vararg. This provides more flexibility when creating objects in different states.

2. Assign target to another selector

The second variant of the builder allows assigning the value of the target to a destination selector:

 Assign.valueOf(origin).to(destination)
 

The value can be assigned as is, or mapped to another value using the as(Function) method:

Example:

 Assignment assignment = Assign.valueOf(field(Address::getCountryCode))
      .to(field(Address::getCountryName))
      .as((String countryCode) -> getCountryName(countryCode));
 

Parameters:

target - the selector

Returns:

builder for constructing an assignment

Since:

3.0.0

See Also:

• valueOf(GetMethodSelector)
• valueOf(Class)

valueOf

@ExperimentalApi
public static <T> ValueOf valueOf(Class<T> target)

Creates an assignment for a given target type. This is a shorthand API of valueOf(TargetSelector) allowing:

 Assign.valueOf(all(Integer.class))
 

to be specified as a slightly shorter version:

 Assign.valueOf(Integer.class)
 

Type Parameters:

T - the type of value

Parameters:

target - the type of the target's value

Returns:

builder for constructing an assignment

Since:

3.0.0

See Also:

• valueOf(TargetSelector)

valueOf

@ExperimentalApi
public static <T,
R> ValueOf valueOf(GetMethodSelector<T,R> target)

Creates an assignment for a given target method reference. This is a shorthand API of valueOf(TargetSelector) allowing:

 Assign.valueOf(field(Pojo::getValue))
 

to be specified as a slightly shorter version:

 Assign.valueOf(Pojo::getValue)
 

Type Parameters:

T - type declaring the method

R - return type of the method

Parameters:

target - the method reference for the target field

Returns:

builder for constructing an assignment

Since:

3.0.0

See Also:

• valueOf(TargetSelector)

given

@ExperimentalApi
public static GivenOriginDestination given(TargetSelector origin,
 TargetSelector destination)

Creates a conditional assigment for a given pair of origin and destination selectors. This method allows mapping predicates to destination values, and also supports else semantics with the following syntax:

 Assign.given(origin, destination)
     .set(originPredicate1, "value1")
     .set(originPredicate2, "value2")
     .supply(originPredicate3, () -> getValue3())
     .generate(originPredicate4, gen -> gen.oneOf("value4A", "value4B"))
     .elseSet("other-value");
 

A destination will be set to a given value only if the corresponding predicate is satisfied. If none of the predicates match, the value from the else branch will be set. Note that the else branch is optional. If it is not specified, a random value will be generated when none of the predicates match.

Example:

 Assignment phoneCountryCode = Assign.given(field(Address::getCountry), field(Phone::getCountryCode))
     .set(When.isIn("Canada", "USA"), "+1")
     .set(When.is("Italy"), "+39")
     .set(When.is("Poland"), "+48")
     .set(When.is("Germany"), "+49")
     .elseSupply(() -> Assertions.fail("unexpected country"));

 Person person = Instancio.of(Person.class)
     .generate(field(Address::getCountry), gen -> gen.oneOf("Canada", "Germany", "Italy", "Poland", "USA"))
     .assign(phoneCountryCode)
     .create();
 

In the above example, the generated country names should match one of the assignment predicates, therefore the assertion failure in elseSupply() should not be reachable, and could be omitted.

Parameters:

origin - selector whose target the origin predicate will be evaluated against

destination - selector whose targets will be set to a given value if the origin predicate is satisfied

Returns:

builder for constructing a conditional assignment

Since:

3.0.0

See Also:

• given(TargetSelector)

given

@ExperimentalApi
public static GivenOrigin given(TargetSelector origin)

Creates a conditional for a given origin and one or more destination selectors. This method allows mapping an origin to different destinations, but unlike given(TargetSelector, TargetSelector) this method does not support else semantics:

 Assign.given(origin)
     .is("foo")
     .set(destination1, "value1")
     .set(destination2, "value2")
     .supply(destination3, () -> getValue3())
     .generate(destination4, gen -> gen.oneOf("value4A", "value4B"));
 

All destinations will be set to the corresponding values if the predicate is satisfied.

Example:

 Assignment orderFields = Assign.given(Order::getStatus)
     .is(OrderStatus.CANCELLED)
     .set(field(Order::getCancellationReason), "Shipping delays")
     .generate(field(Order::getCancellationDate), gen -> gen.temporal().localDate().past());

 List<Order> orders = Instancio.ofList(Order.class)
     .size(20)
     .assign(orderFields)
     .create();
 

The above snippet will generate a list of random orders. If an order with a CANCELLED status is generated, the order will have the expected values as specified by the assignment. It is possible to specify different values for other order statuses. Since the example above does not specify this, for all other order statuses, random values will be generated.

Parameters:

origin - selector whose target the origin predicate will be evaluated against

Returns:

builder for constructing a conditional assignment

Since:

3.0.0

See Also:

• given(TargetSelector, TargetSelector)
• given(Class)
• given(GetMethodSelector)

given

@ExperimentalApi
public static <T,
R> GivenOrigin given(GetMethodSelector<T,R> origin)

Creates a conditional assignment for a given origin method reference and one or more destination selectors. This is a shorthand API of given(TargetSelector) allowing:

 Assign.given(field(Pojo::getValue))
 

to be specified as a slightly shorter version:

 Assign.given(Pojo::getValue)
 

Type Parameters:

T - type declaring the method

R - return type of the method

Parameters:

origin - a method reference for the origin value

Returns:

builder for constructing a conditional assignment

Since:

3.0.0

See Also:

• given(TargetSelector)

given

@ExperimentalApi
public static <T> GivenOrigin given(Class<T> origin)

Creates a conditional assignment for a given origin type. This is a shorthand API of given(TargetSelector) allowing:

 Assign.given(all(Integer.class))
 

to be specified as a slightly shorter version:

 Assign.given(Integer.class)
 

Type Parameters:

T - the type of value

Parameters:

origin - type of the origin value

Returns:

builder for constructing a conditional assignment

Since:

3.0.0

See Also:

• given(TargetSelector)