Additive builder settersedit
Properties of type
Map are exposed by object builders as a set of overloaded
additive-only methods that update the property value, by appending to lists and adding
new entries to maps (or replacing existing ones).
Object builders create immutable objects, and this also applies to list and map properties that are made immutable at object construction time.
// Prepare a list of index names List<String> names = Arrays.asList("idx-a", "idx-b", "idx-c"); // Prepare cardinality aggregations for fields "foo" and "bar" Map<String, Aggregation> cardinalities = new HashMap<>(); cardinalities.put("foo-count", Aggregation.of(a -> a.cardinality(c -> c.field("foo")))); cardinalities.put("bar-count", Aggregation.of(a -> a.cardinality(c -> c.field("bar")))); // Prepare an aggregation that computes the average of the "size" field final Aggregation avgSize = Aggregation.of(a -> a.avg(v -> v.field("size"))); SearchRequest search = SearchRequest.of(r -> r // Index list: // - add all elements of a list .index(names) // - add a single element .index("idx-d") // - add a vararg list of elements .index("idx-e", "idx-f", "idx-g") // Sort order list: add elements defined by builder lambdas .sort(s -> s.field(f -> f.field("foo").order(SortOrder.Asc))) .sort(s -> s.field(f -> f.field("bar").order(SortOrder.Desc))) // Aggregation map: // - add all entries of an existing map .aggregations(cardinalities) // - add a key/value entry .aggregations("avg-size", avgSize) // - add a key/value defined by a builder lambda .aggregations("price-histogram", a -> a.histogram(h -> h.field("price"))) );
List and map values are never
The Elasticsearch API has a lot of optional properties. For single-valued properties, the Java API Client
represents missing optional values as
null. Applications therefore have to null-check
optional values before using them.
For lists and maps however, applications often only care about whether they’re empty or not,
or even just iterate on their content. Using
null values is then cumbersome. To avoid this,
Java API Client collection properties are never
null, and missing optional collections are
returned as an empty collection.
If you ever need to distinguish between a missing (undefined) optional collection and an
effectively-empty collection returned by Elasticsearch, the
ApiTypeHelper class provides a utility
method to distinguish them:
NodeStatistics stats = NodeStatistics.of(b -> b .total(1) .failed(0) .successful(1) ); // The `failures` list was not provided. // - it's not null assertNotNull(stats.failures()); // - it's empty assertEquals(0, stats.failures().size()); // - and if needed we can know it was actually not defined assertFalse(ApiTypeHelper.isDefined(stats.failures()));
The source code for the examples above can be found in the Java API Client tests.