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:

  • 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

      @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

      @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:

    • 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

      @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

      @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

      @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: