Lists and maps
editLists and maps
editAdditive builder setters
editProperties of type List
and 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 null
editThe 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.