T
- a type of the message which is returned by the implementations TargetBuilder.build()
B
- a type of the builder implementationspublic abstract class TargetBuilder<T extends com.google.protobuf.Message,B extends TargetBuilder<T,B>>
extends java.lang.Object
Message instances
which have a Target
and a FieldMask
as attributes.
The Target
matching the builder configuration is created with TargetBuilder.buildTarget()
,
while the FieldMask
is composed with TargetBuilder.composeMask()
.
The public API of this class is inspired by SQL syntax:
select(Customer.class) // returning <AbstractTargetBuilder> descendant instance
.byId(westCoastCustomerIds())
.withMask("name", "address", "email")
.where(eq("type", "permanent"),
eq("discountPercent", 10),
eq("companySize", Company.Size.SMALL))
.build();
Calling any of the builder methods overrides the previous call of the given method or any of its overloads. For example, calling sequentially:
builder.withMask(mask1)
.withMask(mask2)
// optionally some other invocations
.withMask(mask3)
.build();
is equivalent to calling:
builder.withMask(mask3)
.build();
Modifier and Type | Method and Description |
---|---|
abstract T |
build() |
B |
byId(java.lang.Integer... ids)
Sets the ID predicate to the
Query . |
B |
byId(java.lang.Iterable<?> ids)
Sets the ID predicate to the targets of the request.
|
B |
byId(java.lang.Long... ids)
Sets the ID predicate to the
Query . |
B |
byId(com.google.protobuf.Message... ids)
Sets the ID predicate to the
Query . |
B |
byId(java.lang.String... ids)
Sets the ID predicate to the
Query . |
java.lang.String |
toString() |
B |
where(io.spine.client.CompositeFilter... predicate)
Sets the predicates for the
Query . |
B |
where(io.spine.client.Filter... predicate)
Sets the predicates for the
Query . |
B |
withMask(java.lang.Iterable<java.lang.String> fieldNames)
Sets the entity fields to retrieve.
|
B |
withMask(java.lang.String... fieldNames)
Sets the entity fields to retrieve.
|
public B byId(java.lang.Iterable<?> ids)
Though it's not prohibited at compile-time, please make sure to pass instances of the same type to the argument of this method. Moreover, the instances must be of the type of the query target type identifier.
This method or any of its overloads do not check these constraints and assume they are followed by the caller.
If there are no IDs (i.e. and empty Iterable
is passed), the query retrieves all
the records regardless of their IDs.
ids
- the values of the IDs to look uppublic B byId(com.google.protobuf.Message... ids)
Query
.ids
- the values of the IDs to look upTargetBuilder.byId(Iterable)
public B byId(java.lang.String... ids)
Query
.ids
- the values of the IDs to look upTargetBuilder.byId(Iterable)
public B byId(java.lang.Integer... ids)
Query
.ids
- the values of the IDs to look upTargetBuilder.byId(Iterable)
public B byId(java.lang.Long... ids)
Query
.ids
- the values of the IDs to look upTargetBuilder.byId(Iterable)
public B where(io.spine.client.Filter... predicate)
Query
.
If there are no Filter
s (i.e. the passed array is empty),
all the records will be retrieved regardless of the column values.
The multiple parameters passed into this method are considered to be joined in
a conjunction (ALL
operator), i.e. a record matches this query only if it matches all of these parameters.
predicate
- the Filter
s to filter the query resultsfor a convenient way to create {@link io.spine.client.Filter} instances
,
TargetBuilder.where(io.spine.client.CompositeFilter...)
public B where(io.spine.client.CompositeFilter... predicate)
Query
.
If there are no Filter
s (i.e. the passed array is empty),
all the records will be retrieved regardless the column values.
The input values represent groups of simple filters joined with a composite operator.
The input filter groups are effectively joined between each other by
ALL
operator, i.e. a
record matches
this query if it matches all the composite filters.
Example of usage:
factory.select(Customer.class)
// Possibly other parameters
.where(all(ge("companySize", 50), le("companySize", 1000)),
either(gt("establishedTime", twoYearsAgo), eq("country", "Germany")))
.build();
In the example above, the Customer
records match the built query if they
represent
companies that have their company size between 50 and 1000 employees and either have been
established less than two years ago, or originate from Germany.
Note that the filters which belong to different all(...)
groups
may be represented as a single all(...)
group. For example, two
following queries would be identical:
// Option 1
factory.select(Customer.class)
.where(all(
eq("country", "Germany")),
all(
ge("companySize", 50),
le("companySize", 100)))
.build();
// Option 2 (identical)
factory.select(Customer.class)
.where(all(
eq("country", "Germany"),
ge("companySize", 50),
le("companySize", 100)))
.build();
The Option 1
is recommended in this case, since the filters are grouped
logically,
though both builders produce effectively the same Query
instances.
Note, that
those instances may not be equal in terms of Object.equals(Object)
method.
predicate
- a number of CompositeFilter
instances forming the query
predicatefor a convenient way to create {@link io.spine.client.CompositeFilter}
instances
public B withMask(java.lang.Iterable<java.lang.String> fieldNames)
The names of the fields must be formatted according to the FieldMask
specification.
If there are no fields (i.e. an empty Iterable
is passed), all the fields will
be retrieved.
fieldNames
- the fields to querypublic B withMask(java.lang.String... fieldNames)
The names of the fields must be formatted according to the FieldMask
specification.
If there are no fields (i.e. an empty array is passed), all the fields will be retrieved.
fieldNames
- the fields to querypublic abstract T build()
public java.lang.String toString()
toString
in class java.lang.Object