Package org.instancio

Interface FieldSelectorBuilder

All Superinterfaces:

ConvertibleToScope, DepthPredicateSelector, DepthSelector, GroupableSelector, LenientSelector, ScopeableSelector, TargetSelector, WithinScope

public interface FieldSelectorBuilder
extends DepthSelector, DepthPredicateSelector, ScopeableSelector

A builder for constructing predicate-based field selectors.

An instance of the builder can be obtained using Select.fields(). Other methods from this class can be chained to form logical AND relationships, for example:

 fields().ofType(String.class).annotated(Foo.class).annotated(Bar.class)
 

will match String fields annotated @Foo and @Foo.

Since:

1.6.0

See Also:

• Select
• PredicateSelector
• TargetSelector

Method Summary

Modifier and Type	Method	Description
<A extends Annotation> FieldSelectorBuilder	annotated(Class<? extends A> annotation)	Matches fields annotated with the specified annotation, ignoring inherited annotations.
ScopeableSelector	atDepth(int depth)	Restricts this selector's targets to the specified depth.
ScopeableSelector	atDepth(Predicate<Integer> atDepth)	Restricts this selector's targets to a depth that satisfies the given predicate.
FieldSelectorBuilder	declaredIn(Class<?> type)	Matches fields declared in the specified class.
FieldSelectorBuilder	matching(String regex)	Matches field names using the specified regular expression.
FieldSelectorBuilder	named(String fieldName)	Matches fields with the specified name.
FieldSelectorBuilder	ofType(Class<?> fieldType)	Matches fields against the specified type, including subtypes.
Scope	toScope()	Scope representation of a selector.
GroupableSelector	within(Scope... scopes)	Specifies the scope for this selector in order to narrow down its target.

Methods inherited from interface org.instancio.ScopeableSelector

lenient

Method Details

named

FieldSelectorBuilder named(String fieldName)

Matches fields with the specified name.

Parameters:

fieldName - exact field name to match

Returns:

selector builder

Since:

1.6.0

See Also:

• matching(String)

matching

FieldSelectorBuilder matching(String regex)

Matches field names using the specified regular expression.

Parameters:

regex - for matching field names

Returns:

selector builder

Since:

2.2.0

See Also:

• named(String)

ofType

FieldSelectorBuilder ofType(Class<?> fieldType)

Matches fields against the specified type, including subtypes. For example, selecting fields ofType(Collection.class} will match fields declared as List or Set.

Note: this method will not match fields declared as a TypeVariable. For instance, in the following snippet, even though T is bound to String type, the selector ofType(String.class) will not match the field. In this case, targeting the field by name would be a better option.

 class Item<T> {
     private T value;
 }

 Item<String> result = Instancio.of(new TypeToken<Item<String>>() {})
     .set(fields().ofType(String.class), "foo") // will not match Item.value
     .create();

 assertThat(result.getValue()).isNotEqualTo("foo");
 

Parameters:

fieldType - field type to match

Returns:

selector builder

Since:

1.6.0

declaredIn

FieldSelectorBuilder declaredIn(Class<?> type)

Matches fields declared in the specified class.

Parameters:

type - class that declares target field(s)

Returns:

selector builder

Since:

1.6.0

annotated

<A extends Annotation> FieldSelectorBuilder annotated(Class<? extends A> annotation)

Matches fields annotated with the specified annotation, ignoring inherited annotations.

The method can be chained to require multiple annotations.

Type Parameters:

A - annotation type

Parameters:

annotation - declared annotation to match

Returns:

selector builder

Since:

1.6.0

atDepth

ScopeableSelector atDepth(int depth)

Restricts this selector's targets to the specified depth. The selector will only apply to targets at the specified depth.

When a selector with atDepth(N) is converted using toScope(), the semantics of the Selector.within(Scope...) method still apply, meaning that the selection applies to targets at depth equal to or greater than N.

The root object is considered to be at depth 0.

Specified by:

atDepth in interface DepthSelector

Parameters:

depth - the depth at which the selector should apply

Returns:

a selector restricted to the specified depth

Since:

2.14.0

See Also:

• DepthPredicateSelector

atDepth

ScopeableSelector atDepth(Predicate<Integer> atDepth)

Restricts this selector's targets to a depth that satisfies the given predicate.

For example, a predicate atDepth(depth -> depth == 1) will restrict the selector to targets at depth 1 only.

The root object is considered to be at depth 0.

Specified by:

atDepth in interface DepthPredicateSelector

Parameters:

atDepth - the predicate specifying the acceptable depth

Returns:

a selector restricted to the specified depth

Since:

2.14.0

See Also:

• DepthSelector

within

@ExperimentalApi
GroupableSelector within(Scope... scopes)

Specifies the scope for this selector in order to narrow down its target.

For example, given the following classes:

 record Phone(String countryCode, String number) {}

 record Person(Phone home, Phone cell) {}
 

setting home and cell phone numbers to different values would require differentiating between two field(Phone::number) selectors. This can be achieved using scopes as follows:

 Scope homePhone = field(Person::home).toScope();
 Scope cellPhone = field(Person::cell).toScope();

 Person person = Instancio.of(Person.class)
     .set(field(Phone::number).within(homePhone), "777-88-99")
     .set(field(Phone::number).within(cellPhone), "123-45-67")
     .create();
 

See Selector Scopes section of the user guide for details.

Specified by:

within in interface ScopeableSelector

Specified by:

within in interface WithinScope

Parameters:

scopes - one or more scopes to apply

Returns:

a selector with the specified scope

Since:

4.2.0

toScope

@ExperimentalApi
Scope toScope()

Scope representation of a selector.

Specified by:

toScope in interface ConvertibleToScope

Returns:

scope

Since:

4.2.0