Why can't Builders be reused after being build()-t

Elastic Stack Elasticsearch
1

I keep getting caught out by Error: java.lang.IllegalStateException: Object builders can only be used once errors.
This is my fault for creating a builder outside of the query lambda and then calling builder.build() inside the lambda, eg:

BoolQuery.Builder bool = new BoolQuery.Builder().filter(....);
if (someCondition) {
    bool.filter(f -> another conditional filter);
}
SearchResponse<ModeClass> response = elasticsearchService.search(s -> s
    .query(q -> q.bool(bool.build())), ModelClass.class)
    ...

I was going to change code like this to call build() outside of the lambda and pass it in, like so:

BoolQuery.Builder bool = new BoolQuery.Builder().filter(....);
if (someCondition) {
    bool.filter(f -> another conditional filter);
}
Bool.Query boolQuery = bool.build();
SearchResponse<ModelClass> response = elasticsearchService.search(s -> s
    .query(q -> q.bool(boolQuery)), ModelClass.class)
    ...

This way, if the lamda is re-executed (by a resilience4j Retry, for example), we're not calling build() multiple times on the builder.

BUT I notice the docs state:

Builders are transient objects that should not be reused after calling build()

Does this mean this is a bad idea? Why?
Once a builder is built, why can't it be used multiple times?

2

AFAICT in the latter code you're not using the builder after calling build() so it looks ok to me.

It's a bad idea (and forbidden) to re-use builders because they may share their underlying data structures with the object that is eventually built, so mutating the builder may also inadvertently mutate any previously-built requests too.

3

Hello!

To further elaborate on @DavidTurner's reply, every builder that includes a Collection creates that as Immutable, so reusing the same builder in that case would result in an exception.

Nevermind, even the Collections of an output object can be edited through the builder, so it's really safer to use them just once.