Package org.instancio

Class Select

java.lang.Object
org.instancio.Select
public final class Select extends Object
Provides static factory methods for creating selectors and selector scopes. Selectors are used for targeting fields and classes. Instancio supports two types of selectors: regular and predicate-based.

Regular selectors allow matching by exact class (not including subtypes) and field:

Predicate selectors, as the name suggests, use a Predicate for matching targets:

The first two allow constructing predicates using convenience builder methods. The last two methods can be used with arbitrary predicates where the builders are not sufficient.

It should be noted that regular selectors have higher precedence than predicate selectors. See the Selectors section of the User Guide for more details.

Since:
1.2.0
See Also:

  • Method Details

    • fields

      public static FieldSelectorBuilder fields()
      Provides a builder for selecting fields based on Predicates. This method can be used for selecting multiple fields in different classes. The returned builder offers convenience methods for constructing the predicate.

      The following example will match all fields named lastModified declared in the Person and other classes referenced from Person.

      
 Person person = Instancio.of(Person.class)
     .supply(fields().named("lastModified"), () -> LocalDateTime.now())
     .create();

      Specifying only fields() (without further predicates) will match all fields declared across the class tree.

      The alternative method fields(Predicate) can be used to specify a predicate directly.

      Returns:
      predicate selector builder for matching fields
      Since:
      1.6.0
      See Also:

    • types

      public static TypeSelectorBuilder types()
      Provides a builder for selecting types based on Predicates. This method can be used for selecting multiple types. The returned builder offers convenience methods for constructing the predicate.

      The following example will match all types annotated @Embeddable.

      
 Person person = Instancio.of(Person.class)
     .set(types().annotated(Embeddable.class), null)
     .create();

      Specifying only types() (without further predicates) will match all types referenced in the class tree.

      The alternative method types(Predicate) can be used to specify a predicate directly.

      Returns:
      predicate selector builder for matching types
      Since:
      1.6.0
      See Also:

    • fields

      public static PredicateSelector fields(Predicate<Field> predicate)
      Select all fields matching the specified predicate.
      Parameters:
      predicate - for matching fields
      Returns:
      a predicate selector
      Since:
      1.6.0
      See Also:

    • types

      public static PredicateSelector types(Predicate<Class<?>> predicate)
      Select all types matching the specified predicate.
      Parameters:
      predicate - for matching types
      Returns:
      a predicate selector
      Since:
      1.6.0
      See Also:

    • all

      public static Selector all(Class<?> type)
      Select all instances of the given type, not including subtypes.

      If the type is a primitive or wrapper, this method only selects the specified type. For example:

      • all(int.class) - selects primitive int but not Integer
      • all(Integer.class) - selects Integer wrapper but not primitive int

      In order to select both, primitive int and wrapper, use the allInts().

      Parameters:
      type - to select
      Returns:
      a selector for given class
      Since:
      1.2.0

    • all

      public static SelectorGroup all(GroupableSelector... selectors)
      A convenience method for combining multiple selectors.

      Example: 

      
 Person person = Instancio.of(Person.class)
     .withNullable(all(
         all(Gender.class),
         all(Phone.class),
         field(Person::getDateOfBirth)
     ))
     .create()
      Parameters:
      selectors - to combine
      Returns:
      a group containing given selectors
      Since:
      1.3.0

    • field

      public static Selector field(Class<?> declaringClass, String fieldName)
      Selects a field by name in the specified class. The name must match exactly.
      Parameters:
      declaringClass - class declaring the field
      fieldName - field name to select
      Returns:
      a selector for given field
      Throws:
      InstancioApiException - if the class has no field with the specified name
      Since:
      1.2.0
      See Also:

    • field

      public static Selector field(String fieldName)
      Selects a field by name declared in the class being created.

      Example 

      
 Person person = Instancio.of(Person.class)
     .ignore(field("fullName")) // Person.fullName
     .create();

      Parameters:
      fieldName - field name to select
      Returns:
      a selector for given field
      Throws:
      InstancioApiException - if the class being created has no field with the specified name
      Since:
      1.2.0
      See Also:

    • field

      @ExperimentalApi public static <T, R> Selector field(GetMethodSelector<T,R> methodReference)
      Selects a field based on the given method reference.

      Internally, the method reference is mapped to a regular field selector as returned by field(Class, String). Therefore, this method only works for classes with expected field and method naming conventions:

      • Java beans convention with "get" and "is" prefixes.
      • Java records convention where method names match property names.

      Examples: 

      
 // Java beans naming convention
 field(Person::getName)  -> field(Person.class, "name")
 field(Person::isActive) -> field(Person.class, "active")

 // Property-style naming convention (e.g. Java records)
 field(Person::name)     -> field(Person.class, "name")
 field(Person::isActive) -> field(Person.class, "isActive")

      Note: for a method reference with a generic return type, the type must be specified explicitly, for example by assigning the method reference to a variable: 

      
 class Item<T> {
     private T value;

     T getValue() { // generic return type
         return value;
     }
 }

 GetMethodSelector<Item<String>, String> getterSelector = Item::getValue;
 Select.field(getterSelector)
      Type Parameters:
      T - type declaring the method
      R - return type of the method
      Parameters:
      methodReference - method reference from which field name will be resolved
      Returns:
      a field selector matching the given method reference
      Since:
      2.3.0
      See Also:

    • root

      public static TargetSelector root()
      Selects the root object.
      Returns:
      the selector for the root object
      Since:
      2.0.0

    • allStrings

      public static Selector allStrings()
      Shorthand for all(String.class).
      Returns:
      selector for all Strings
      Since:
      1.2.0

    • allBytes

      public static Selector allBytes()
      Selects all bytes, primitive and wrapper.
      Returns:
      selector for all bytes
      Since:
      1.2.0

    • allFloats

      public static Selector allFloats()
      Selects all floats, primitive and wrapper.
      Returns:
      selector for all floats
      Since:
      1.2.0

    • allShorts

      public static Selector allShorts()
      Selects all shorts, primitive and wrapper.
      Returns:
      selector for all shorts
      Since:
      1.2.0

    • allInts

      public static Selector allInts()
      Selects all integers, primitive and wrapper.
      Returns:
      selector for all integers
      Since:
      1.2.0

    • allLongs

      public static Selector allLongs()
      Selects all longs, primitive and wrapper.
      Returns:
      selector for all longs
      Since:
      1.2.0

    • allDoubles

      public static Selector allDoubles()
      Selects all doubles, primitive and wrapper.
      Returns:
      selector for all doubles
      Since:
      1.2.0

    • allBooleans

      public static Selector allBooleans()
      Selects all booleans, primitive and wrapper.
      Returns:
      selector for all booleans
      Since:
      1.2.0

    • allChars

      public static Selector allChars()
      Selects all characters, primitive and wrapper.
      Returns:
      selector for all characters
      Since:
      1.2.0

    • scope

      public static Scope scope(Class<?> targetClass, String fieldName)
      Creates a scope for narrowing down a selector's target to a field of the specified class.

      For example, the following will set all lists within Person.address object to an empty list. 

      
 Person person = Instancio.of(Person.class)
     .set(all(List.class).within(scope(Person.class, "address")), Collections.emptyList())
     .create();
      Parameters:
      targetClass - of the scope
      fieldName - declared by the target class
      Returns:
      a scope for fine-tuning a selector
      Since:
      1.3.0
      See Also:

    • scope

      public static Scope scope(Class<?> targetClass)
      Creates a selector scope for narrowing down a selector's target to the specified class.

      For example, assuming a Customer class that has a CustomerConsent class. the following will set all booleans within CustomerConsent to true. 

      
 Customer customer = Instancio.of(Customer.class)
     .set(allBooleans().within(scope(CustomerConsent.class)), true)
     .create();

      Note: scopes can only be applied to regular selectors. Predicate selectors, listed below, cannot be scoped.

      Parameters:
      targetClass - of the scope
      Returns:
      a scope for fine-tuning a selector
      Since:
      1.3.0

    • scope

      public static <T, R> Scope scope(GetMethodSelector<T,R> methodReference)
      Creates a scope for narrowing down a selector's target to a matching the specified method reference.

      This is a convenience method for scope(Class, String) that avoids referring to a field by its name.

      Type Parameters:
      T - type declaring the method
      R - return type of the method
      Parameters:
      methodReference - method reference from which field name will be resolved
      Returns:
      a scope for fine-tuning a selector
      Since:
      3.0.0
      See Also: