Class Select
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 Summary
Modifier and TypeMethodDescriptionstatic Selector
Select all instances of the given type, not including subtypes.static SelectorGroup
all
(GroupableSelector... selectors) A convenience method for combining multiple selectors.static Selector
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
Selects all doubles, primitive and wrapper.static Selector
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
Selects all shorts, primitive and wrapper.static Selector
Shorthand forall(String.class)
.static Selector
Selects a field by name in the specified class.static Selector
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 onPredicates
.static PredicateSelector
Select all fields matching the specified predicate.static TargetSelector
root()
Selects the root object.static Scope
Creates a selector scope for narrowing down a selector's target to the specified class.static Scope
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 TypeSelectorBuilder
types()
Provides a builder for selecting types based onPredicates
.static PredicateSelector
Select all types matching the specified predicate.
-
Method Details
-
fields
Provides a builder for selecting fields based onPredicates
. 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 thePerson
and other classes referenced fromPerson
.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
Provides a builder for selecting types based onPredicates
. 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
Select all fields matching the specified predicate.- Parameters:
predicate
- for matching fields- Returns:
- a predicate selector
- Since:
- 1.6.0
- See Also:
-
types
Select all types matching the specified predicate.- Parameters:
predicate
- for matching types- Returns:
- a predicate selector
- Since:
- 1.6.0
- See Also:
-
all
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 primitiveint
but notInteger
all(Integer.class)
- selectsInteger
wrapper but not primitiveint
In order to select both, primitive
int
and wrapper, use theallInts()
.- Parameters:
type
- to select- Returns:
- a selector for given class
- Since:
- 1.2.0
-
all
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
Selects a field by name in the specified class. The name must match exactly.- Parameters:
declaringClass
- class declaring the fieldfieldName
- 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
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
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 methodR
- 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
Selects the root object.- Returns:
- the selector for the root object
- Since:
- 2.0.0
-
allStrings
Shorthand forall(String.class)
.- Returns:
- selector for all Strings
- Since:
- 1.2.0
-
allBytes
Selects all bytes, primitive and wrapper.- Returns:
- selector for all bytes
- Since:
- 1.2.0
-
allFloats
Selects all floats, primitive and wrapper.- Returns:
- selector for all floats
- Since:
- 1.2.0
-
allShorts
Selects all shorts, primitive and wrapper.- Returns:
- selector for all shorts
- Since:
- 1.2.0
-
allInts
Selects all integers, primitive and wrapper.- Returns:
- selector for all integers
- Since:
- 1.2.0
-
allLongs
Selects all longs, primitive and wrapper.- Returns:
- selector for all longs
- Since:
- 1.2.0
-
allDoubles
Selects all doubles, primitive and wrapper.- Returns:
- selector for all doubles
- Since:
- 1.2.0
-
allBooleans
Selects all booleans, primitive and wrapper.- Returns:
- selector for all booleans
- Since:
- 1.2.0
-
allChars
Selects all characters, primitive and wrapper.- Returns:
- selector for all characters
- Since:
- 1.2.0
-
scope
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 scopefieldName
- declared by the target class- Returns:
- a scope for fine-tuning a selector
- Since:
- 1.3.0
- See Also:
-
scope
Creates a selector scope for narrowing down a selector's target to the specified class.For example, assuming a
Customer
class that has aCustomerConsent
class. the following will set all booleans withinCustomerConsent
totrue
.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
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 methodR
- 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:
-