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:

• all(Class)
• field(GetMethodSelector)
• field(Class, String)
• field(String)

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

• fields()
• types()
• fields(Predicate)
• types(Predicate)

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:

• Selector
• SelectorGroup
• PredicateSelector
• TargetSelector
• GroupableSelector

Method Summary

Modifier and Type	Method	Description
static Selector	all(Class<?> type)	Select all instances of the given type, not including subtypes.
static SelectorGroup	all(GroupableSelector... selectors)	A convenience method for combining multiple selectors.
static Selector	allBooleans()	Selects all booleans, primitive and wrapper.
static Selector	allBytes()	Selects all bytes, primitive and wrapper.
static Selector	allChars()	Selects all characters, primitive and wrapper.
static Selector	allDoubles()	Selects all doubles, primitive and wrapper.
static Selector	allFloats()	Selects all floats, primitive and wrapper.
static Selector	allInts()	Selects all integers, primitive and wrapper.
static Selector	allLongs()	Selects all longs, primitive and wrapper.
static Selector	allShorts()	Selects all shorts, primitive and wrapper.
static Selector	allStrings()	Shorthand for all(String.class).
static Selector	field(Class<?> declaringClass, String fieldName)	Selects a field by name in the specified class.
static Selector	field(String fieldName)	Selects a field by name declared in the class being created.
static <T, R> Selector	field(GetMethodSelector<T,R> methodReference)	Selects a field based on the given method reference.
static FieldSelectorBuilder	fields()	Provides a builder for selecting fields based on Predicates.
static PredicateSelector	fields(Predicate<Field> predicate)	Select all fields matching the specified predicate.
static TargetSelector	root()	Selects the root object.
static Scope	scope(Class<?> targetClass)	Creates a selector scope for narrowing down a selector's target to the specified class.
static Scope	scope(Class<?> targetClass, String fieldName)	Creates a scope for narrowing down a selector's target to a field of the specified class.
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.
static Scope	scope(PredicateSelector selector)	Creates a scope from the given predicate selector.
static Selector	setter(Class<?> declaringClass, String methodName)	Selects a setter method by name in the specified class.
static Selector	setter(Class<?> declaringClass, String methodName, Class<?> parameterType)	Selects a setter method by name and parameter type in the specified class.
static Selector	setter(String methodName)	Selects a setter by name declared in the class being created.
static <T, U> Selector	setter(SetMethodSelector<T,U> methodReference)	Selects a setter method based on the given method reference.
static TypeSelectorBuilder	types()	Provides a builder for selecting types based on Predicates.
static PredicateSelector	types(Predicate<Class<?>> predicate)	Select all types matching the specified predicate.

Methods inherited from class java.lang.Object

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

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:

• fields(Predicate)
• types(Predicate)
• types()

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:

• types(Predicate)
• fields(Predicate)
• fields()

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:

• fields()
• types()
• types(Predicate)

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:

• types()
• fields()
• fields(Predicate)

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(String)
• fields()
• fields(Predicate)

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(Class, String)
• fields()
• fields(Predicate)

field

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:

 class Item<T> {
     private T value;

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

 // Option 1:
 Select.field(Item<String>::getValue)

 // Option 2:
 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:

• field(Class, String)

setter

@ExperimentalApi
public static Selector setter(String methodName)

Selects a setter by name declared in the class being created. The setter method must have exactly one parameter. Since this method resolves the setter by name only (ignoring the parameter type) it should only be used if there are no overloaded setters.

Example

 Person person = Instancio.of(Person.class)
     .ignore(setter("setFullName")) // Person.setFullName
     .create();
 

Note: setter selectors can only be used if Keys.ASSIGNMENT_TYPE is set to AssignmentType.METHOD.

Parameters:

methodName - the name of the setter method to select

Returns:

a selector for given method

Throws:

InstancioApiException - if the root class has no method with the specified name

Since:

4.0.0

See Also:

• setter(Class, String)
• setter(Class, String, Class)

setter

@ExperimentalApi
public static Selector setter(Class<?> declaringClass,
 String methodName)

Selects a setter method by name in the specified class. The method must have exactly one parameter. Since this method resolves the setter by name only (ignoring the parameter type) it should only be used if there are no overloaded setters.

Note: setter selectors can only be used if Keys.ASSIGNMENT_TYPE is set to AssignmentType.METHOD.

Parameters:

declaringClass - class declaring the method

methodName - method name to select

Returns:

a selector for given method

Throws:

InstancioApiException - if the class has no method with the specified name

Since:

4.0.0

See Also:

• setter(String)
• setter(SetMethodSelector)

setter

@ExperimentalApi
public static Selector setter(Class<?> declaringClass,
 String methodName,
 Class<?> parameterType)

Selects a setter method by name and parameter type in the specified class.

Note: setter selectors can only be used if Keys.ASSIGNMENT_TYPE is set to AssignmentType.METHOD.

Parameters:

declaringClass - class declaring the method

methodName - method name to select

parameterType - the parameter type of the setter

Returns:

a selector for given method

Throws:

InstancioApiException - if the class has no method with the specified name and parameter type

Since:

4.0.0

setter

@ExperimentalApi
public static <T,
U> Selector setter(SetMethodSelector<T,U> methodReference)

Selects a setter method based on the given method reference.

This selector resolves the class that declares the setter and the method name from the method reference. Since this method resolves the setter by name only (ignoring the parameter type) it should only be used if there are no overloaded setters.

Note: setter selectors can only be used if Keys.ASSIGNMENT_TYPE is set to AssignmentType.METHOD.

Type Parameters:

T - type declaring the method

U - the argument type of the method

Parameters:

methodReference - method reference from which the method will be resolved

Returns:

a method selector matching the given method reference

Since:

4.0.0

See Also:

• setter(Class, String, Class)

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(GetMethodSelector)

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();
 

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:

• scope(Class, String)

scope

@ExperimentalApi
public static Scope scope(PredicateSelector selector)

Creates a scope from the given predicate selector.

Parameters:

selector - a predicate selector to use as the scope

Returns:

a scope for fine-tuning a selector

Since:

4.2.0