Lists and maps
Properties of typeList andMap are exposed by object builders as a set of overloaded additive-only methods thatupdate 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 namesList<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" fieldfinal 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"))));The Elasticsearch API has a lot of optional properties. For single-valued properties, the Java API Client represents missing optional values asnull. 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. Usingnull values is then cumbersome. To avoid this, Java API Client collection properties are nevernull, 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, theApiTypeHelper 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 nullassertNotNull(stats.failures());// - it's emptyassertEquals(0, stats.failures().size());// - and if needed we can know it was actually not definedassertFalse(ApiTypeHelper.isDefined(stats.failures()));The source code for the examples above can be found in theJava API Client tests.