Package org.instancio

Interface CartesianProductApi<T>

Type Parameters:
T - type to create
All Superinterfaces:
InstancioOperations<T>, LenientMode<T>, VerboseMode<T>
@ExperimentalApi public interface CartesianProductApi<T> extends InstancioOperations<T>, LenientMode<T>, VerboseMode<T>
Provides an API for generating the Cartesian product.

This class supports most of the Instancio API methods, but provides additional methods for generating the Cartesian product:

Since:
4.0.0

  • Method Details

    • with

      @ExperimentalApi <V> CartesianProductApi<T> with(TargetSelector selector, V... values)
      Sets a range of values for generating the Cartesian product. The results are returned as a list in lexicographical order using the list() method.

      Example: 

      
 record Widget(String type, int num) {}

 List<Widget> results = Instancio.ofCartesianProduct(Widget.class)
     .with(field(Widget::type), "FOO", "BAR", "BAZ")
     .with(field(Widget::num), 1, 2, 3)
     .list();

      This will produce the following list of Widget objects: 

       [Widget[type=FOO, num=1],
  Widget[type=FOO, num=2],
  Widget[type=FOO, num=3],
  Widget[type=BAR, num=1],
  Widget[type=BAR, num=2],
  Widget[type=BAR, num=3],
  Widget[type=BAZ, num=1],
  Widget[type=BAZ, num=2],
  Widget[type=BAZ, num=3]]

      Limitations

      A selector passed to with() must match a single target. For example, Cartesian product cannot be generated for collection elements: 

      
 record Widget(String type, int num) {}
 record Container(List<Widget> widgets) {}

 List<Container> results = Instancio.ofCartesianProduct(Container.class)
     .with(field(Widget::type), "FOO", "BAR", "BAZ")
     .with(field(Widget::num), 1, 2, 3)
     .list();

      The above will produce an error with a message: "no item is available to emit()".

      Type Parameters:
      V - type of the value
      Parameters:
      selector - for fields and/or classes this method should be applied to
      values - the range of values to generate
      Returns:
      API builder reference
      Since:
      4.0.0

    • list

      @ExperimentalApi List<T> list()
      Returns he Cartesian product generated from values specified via the with(TargetSelector, Object[]) method as a list.
      Returns:
      Cartesian product as a list
      Since:
      4.0.0

    • ignore

      CartesianProductApi<T> ignore(TargetSelector selector)
      Specifies that a class or field should be ignored.

      Example: 

      
 Person person = Instancio.of(Person.class)
     .ignore(field(Phone::getPhoneNumber))
     .ignore(allStrings())
     .create();

      will create a fully populated person, but will ignore the getPhoneNumber field, and all strings.

      Precedence

      This method has higher precedence than other API methods. Once a target is ignored, no other selectors will apply. For example, the following snippet will trigger an unused selector error because field(Phone::getNumber) is redundant: 

      
 Person person = Instancio.of(Person.class)
     .ignore(all(Phone.class))
     .set(field(Phone::getNumber), "123-45-56")
     .create();

      Usage with Java records

      If ignore() targets one of the required arguments of a record constructor, then a default value for the ignored type will be generated.

      Example: 

      
 record PersonRecord(String name, int age) {}

 PersonRecord person = Instancio.of(PersonRecord.class)
     .ignore(allInts())
     .ignore(allStrings())
     .create();

 // will produce: PersonRecord[name=null, age=0]
      Specified by:
      ignore in interface InstancioOperations<T>
      Parameters:
      selector - for fields and/or classes this method should be applied to
      Returns:
      API builder reference
      Since:
      4.0.0

    • withNullable

      CartesianProductApi<T> withNullable(TargetSelector selector)
      Specifies that a field or class is nullable. By default, Instancio assigns non-null values to fields. If marked as nullable, Instancio will generate either a null or non-null value.

      Example: 

      
 Person person = Instancio.of(Person.class)
     .withNullable(allStrings())
     .withNullable(field(Person::getAddress))
     .withNullable(fields().named("lastModified"))
     .create();
      Note: a type marked as nullable using this method is only nullable when declared as a field, but not as a collection element, or map key/value. For example, withNullable(allStrings()) will not generate nulls in a List<String>.
      Specified by:
      withNullable in interface InstancioOperations<T>
      Parameters:
      selector - for fields and/or classes this method should be applied to
      Returns:
      API builder reference
      Since:
      4.0.0

    • set

      <V> CartesianProductApi<T> set(TargetSelector selector, V value)
      Sets a value to matching selector targets.

      Example: if Person class contains a List<Phone>, the following snippet will set all the country code of all phone instances to "+1". 

      
 Person person = Instancio.of(Person.class)
     .set(field(Phone::getCountryCode), "+1")
     .create();

      Note: Instancio will not

      • populate or modify objects supplied by this method
      • apply other set(), supply(), or generate()} methods with matching selectors to the supplied object
      • invoke onComplete() callbacks on supplied instances
      Specified by:
      set in interface InstancioOperations<T>
      Type Parameters:
      V - type of the value
      Parameters:
      selector - for fields and/or classes this method should be applied to
      value - value to set
      Returns:
      API builder reference
      Since:
      4.0.0
      See Also:

    • setModel

      @ExperimentalApi <V> CartesianProductApi<T> setModel(TargetSelector selector, Model<V> model)
      Applies given model to the specified selector.

      For example, given the following classes and Model: 

      
 record Foo(String value) {}
 record Container(Foo fooA, Foo fooB) {}

 Model<Foo> fooModel = Instancio.of(Foo.class)
     .set(field(Foo::value), "foo")
     .toModel();

      The model can be applied to a specific Foo field declared by the Container: 

      
 Container container = Instancio.of(Container.class)
     .setModel(field(Container::fooA), fooModel)
     .create();

      Alternatively, to apply the model to all instances of Foo: 

      
 Container container = Instancio.of(Container.class)
     .setModel(all(Foo.class), fooModel)
     .create();

      Note: the following properties of the supplied model are not applied to the target object:

      • Settings
      • lenient() mode
      • custom seed value

      See the user guide for further details.

      Specified by:
      setModel in interface InstancioOperations<T>
      Type Parameters:
      V - the type of object this model represents
      Parameters:
      selector - to which the model will be applied to
      model - to apply to the given selector's target
      Returns:
      API builder reference
      Since:
      4.4.0

    • supply

      <V> CartesianProductApi<T> supply(TargetSelector selector, Supplier<V> supplier)
      Supplies an object using a Supplier.

      Example: 

      
 Person person = Instancio.of(Person.class)
     .supply(all(LocalDateTime.class), () -> LocalDateTime.now())
     .supply(field(Address::getPhoneNumbers), () -> List.of(
         new PhoneNumber("+1", "123-45-67"),
         new PhoneNumber("+1", "345-67-89")))
     .create();

      Note: Instancio will not

      • populate or modify objects supplied by this method
      • apply other set(), supply(), or generate()} methods with matching selectors to the supplied object
      • invoke onComplete() callbacks on supplied instances

      If you require the supplied object to be populated and/or selectors to be applied, use the InstancioOperations.supply(TargetSelector, Generator) method instead.

      Specified by:
      supply in interface InstancioOperations<T>
      Type Parameters:
      V - type of the supplied value
      Parameters:
      selector - for fields and/or classes this method should be applied to
      supplier - providing the value for given selector
      Returns:
      API builder reference
      Since:
      4.0.0
      See Also:

    • supply

      <V> CartesianProductApi<T> supply(TargetSelector selector, Generator<V> generator)
      Supplies an object using a Generator to matching selector targets. By default, Instancio will populate uninitialised fields of the supplied object. This includes fields with null or default primitive values.

      This method supports the following use cases.

      Generate random objects

      This method provides an instance of Random that can be used to randomise generated objects. For example, if Instancio did not support creation of java.time.Year, it could be generated as follows: 

      
 List<Year> years = Instancio.ofList(Year.class)
     .supply(all(Year.class), random -> Year.of(random.intRange(1900, 2000)))
     .create();

      Provide a partially initialised instance

      In some cases, an object may need to be created in a certain state or instantiated using a specific constructor to be in a valid state. A partially initialised instance can be supplied using this method, and Instancio will populate remaining fields that are null: 

      
 Person person = Instancio.of(Person.class)
     .supply(field(Person::getAddress), random -> new Address("Springfield", "USA"))
     .create();

      This behaviour is controlled by the AfterGenerate hint specified by Generator.hints(). Refer to the Generator.hints() Javadoc for details, or Custom Generators section of the user guide.

      Specified by:
      supply in interface InstancioOperations<T>
      Type Parameters:
      V - type of the value to generate
      Parameters:
      selector - for fields and/or classes this method should be applied to
      generator - that will provide the values
      Returns:
      API builder reference
      Since:
      4.0.0
      See Also:

    • generate

      <V> CartesianProductApi<T> generate(TargetSelector selector, GeneratorSpecProvider<V> gen)
      Customises values using built-in generators provided by the gen parameter, of type Generators.

      Example: 

      
 Person person = Instancio.of(Person.class)
     .generate(field(Person::getAge), gen -> gen.ints().range(18, 100))
     .generate(all(LocalDate.class), gen -> gen.temporal().localDate().past())
     .generate(field(Address::getPhoneNumbers), gen -> gen.collection().size(5))
     .generate(field(Address::getCity), gen -> gen.oneOf("Burnaby", "Vancouver", "Richmond"))
     .create();
      Specified by:
      generate in interface InstancioOperations<T>
      Type Parameters:
      V - type of object to generate
      Parameters:
      selector - for fields and/or classes this method should be applied to
      gen - provider of customisable built-in generators (also known as specs)
      Returns:
      API builder reference
      Since:
      4.0.0
      See Also:

    • generate

      @ExperimentalApi <V> CartesianProductApi<T> generate(TargetSelector selector, GeneratorSpec<V> spec)
      Customises values using arbitrary generator specs.

      Example: 

      
 Person person = Instancio.of(Person.class)
     .generate(field(Person::getAge), Instancio.ints().range(18, 100))
     .generate(all(LocalDate.class),  Instancio.temporal().localDate().past())
     .generate(field(Phone::getNumber),  MyCustomGenerators.phones().northAmerican())
     .create();
      Specified by:
      generate in interface InstancioOperations<T>
      Type Parameters:
      V - type of object to generate
      Parameters:
      selector - for fields and/or classes this method should be applied to
      spec - generator spec
      Returns:
      API builder reference
      Since:
      4.0.0
      See Also:

    • onComplete

      <V> CartesianProductApi<T> onComplete(TargetSelector selector, OnCompleteCallback<V> callback)
      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();

      Note: callbacks are never invoked on objects provided using: 

      
 Person person = Instancio.of(Person.class)
     .set(field(Phone::getCountryCode), "+1")
     .onComplete(field(Phone::getCountryCode), ...) // will not be invoked!
     .create();
      Specified by:
      onComplete in interface InstancioOperations<T>
      Type Parameters:
      V - type of object handled by the callback
      Parameters:
      selector - for fields and/or classes this method should be applied to
      callback - to invoke after object has been populated
      Returns:
      API builder reference
      Since:
      4.0.0

    • subtype

      CartesianProductApi<T> subtype(TargetSelector selector, Class<?> subtype)
      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)
     .subtype(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)
     .subtype(all(List.class), LinkedList.class)
     .create();

      will use the LinkedList implementation for all Lists.

      Specified by:
      subtype in interface InstancioOperations<T>
      Parameters:
      selector - for fields and/or classes this method should be applied to
      subtype - to map the selector to
      Returns:
      API builder reference
      Since:
      4.0.0

    • assign

      @ExperimentalApi CartesianProductApi<T> assign(Assignment... assignments)
      Generates values based on given assignments. An Assignment can be created using one of the builder patterns provided by the Assign class.
      • Assign.valueOf(originSelector).to(destinationSelector)
      • Assign.given(originSelector).satisfies(predicate).set(destinationSelector, value)
      • Assign.given(originSelector, destinationSelector).set(predicate, value)

      For example, the following snippet uses Assign.given(TargetSelector, TargetSelector) to create an assignment that sets Phone.countryCode based on the value of the Address.country field: 

      
 Assignment assignment = 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");

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

      The above API allows specifying different values for a given origin/destination pair. An alternative for creating a conditional is provided by Assign.given(TargetSelector). This method allows specifying different destination selectors for a given origin: 

      
 Assignment shippedOrderAssignment = Assign.given(Order::getStatus)
     .is(OrderStatus.SHIPPED)
     .supply(field(Order::getDeliveryDueDate), () -> LocalDate.now().plusDays(2));

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

 List<Order> orders = Instancio.ofList(Order.class)
     .generate(all(OrderStatus.class), gen -> gen.oneOf(OrderStatus.SHIPPED, OrderStatus.CANCELLED))
     .assign(shippedOrderAssignment, cancelledOrderAssignment)
     .create();

      Limitations of assignments

      Using assignments has a few limitations to be aware of.

      • The origin selector must match a single target. It must not be a SelectorGroup created via Select.all(GroupableSelector...) or primitive/wrapper selector, such as Select.allInts()
      • An assignment where the origin selector's target is within a collection element must have a destination selector within the same collection element.
      • Circular assignments will produce an error.
      Specified by:
      assign in interface InstancioOperations<T>
      Parameters:
      assignments - one or more assignment expressions for setting values
      Returns:
      API builder reference
      Since:
      4.0.0
      See Also:

    • withMaxDepth

      CartesianProductApi<T> withMaxDepth(int maxDepth)
      Specifies the maximum depth for populating an object. The root object is at depth zero. Children of the root object are at depth 1, grandchildren at depth 2, and so on.

      Instancio will populate values up to the maximum depth. Beyond that, values will be null unless the maximum depth is set to a higher value.

      The default maximum depth is defined by Keys.MAX_DEPTH.

      Note: this method is a shorthand for: 

      
 int maxDepth = 5;
 Person person = Instancio.of(Person.class)
     .withSettings(Settings.create().set(Keys.MAX_DEPTH, maxDepth))
     .create();

      If the maximum depth is specified using Settings and this method, then this method takes precedence.

      Specified by:
      withMaxDepth in interface InstancioOperations<T>
      Parameters:
      maxDepth - the maximum depth, must not be negative
      Returns:
      API builder reference
      Since:
      4.0.0

    • withSetting

      <V> CartesianProductApi<T> withSetting(SettingKey<V> key, V value)
      Override setting for the given key with the specified value.
      Specified by:
      withSetting in interface InstancioOperations<T>
      Type Parameters:
      V - the setting value type
      Parameters:
      key - the setting key to override
      value - the setting value
      Returns:
      API builder reference
      Since:
      4.3.1
      See Also:

    • withSettings

      CartesianProductApi<T> withSettings(Settings settings)
      Override default Settings for generating values. The Settings class supports various parameters, such as collection sizes, string lengths, numeric ranges, and so on. For a list of overridable settings, refer to the Keys class.
      Specified by:
      withSettings in interface InstancioOperations<T>
      Parameters:
      settings - to use
      Returns:
      API builder reference
      Since:
      4.0.0
      See Also:

    • withSeed

      CartesianProductApi<T> withSeed(long seed)
      Sets the seed value for the random number generator. If the seed is not specified, a random seed will be used. Specifying the 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.create(UUID.class);

 // Generates the same UUID each time
 UUID result = Instancio.of(UUID.class)
     .withSeed(1234)
     .create();
      Specified by:
      withSeed in interface InstancioOperations<T>
      Parameters:
      seed - for the random number generator
      Returns:
      API builder reference
      Since:
      4.0.0

    • lenient

      CartesianProductApi<T> lenient()
      Disables strict mode in which unused selectors trigger an error. In lenient mode unused selectors are simply ignored.

      This method is a shorthand for: 

      
 Example example = Instancio.of(Example.class)
     .withSetting(Keys.MODE, Mode.LENIENT)
     .create();
      Specified by:
      lenient in interface LenientMode<T>
      Returns:
      API builder reference
      Since:
      4.0.0

    • verbose

      CartesianProductApi<T> verbose()
      Outputs debug information to System.out. This includes:
      • current Settings
      • node hierarchy, including the type and depth of each node
      • seed used to create the object

      Warning: this method has a significant performance impact. It is recommended to remove the call to verbose() after troubleshooting is complete.

      Specified by:
      verbose in interface VerboseMode<T>
      Returns:
      API builder reference
      Since:
      4.0.0