Fix Elasticsearch Client API to be less trappy

[s1monw]

Today we have 3 flavors for each endpoint (for demonstration purpose I only use the _health API)

public interface ClusterAdminClient extends ElasticsearchClient<ClusterAdminClient> {

    ActionFuture<ClusterHealthResponse> health(ClusterHealthRequest request);

    void health(ClusterHealthRequest request, ActionListener<ClusterHealthResponse> listener);

    ClusterHealthRequestBuilder prepareHealth(String... indices);

At least one of them is redundant here already but lemme first explain what is trappy here. If you use the prepareHealth().setWaitForGreenStatus() basically nothing happens. you need to call .get() or .execute().get() or .actionGet() or any of the X flavors. This is not so much of a problem for health because you are waiting for a response, but for endpoints that don't return info that is generally consumed ie. update settings this has in the past lead to so many test bugs that I consider this evil.

Yet, I think we should remove this method entirely and detach the Builders entirely from the Client. Today once a builder is created like this:

  ClusterHealthRequestBuilder builder = client.prepareHealth().setWaitForGreenStatus()

it's tied to a client and if you close that client the builder can't be executed. To me if we even keep the builder in the future it should only have a build() method that returns the corresponding request. Then you can call:

  ClusterHealthRequestBuilder builder = AdminBuilders.health().setWaitForGreenStatus();
  client.health(builder.build());

which is less trappy... oh wait... client.health(builder.build()); returns an ActionFuture<ClusterHealthResponse> which is also redundant IMO. We already have a non-blocking API using a listener which is equally powerful.

I think what we should move to is this:

public interface ClusterAdminClient extends ElasticsearchClient<ClusterAdminClient> {

    ClusterHealthResponse health(ClusterHealthRequest request);

    void health(ClusterHealthRequest request, ActionListener<ClusterHealthResponse> listener);

that way it's clearly a blocking API and it's easy to use. We still keep the builder (for now ;) ) but remove it's coupling to the client which is super trappy.

[rmuir]

This looks much simpler to me.

[mikemccand]

+1

[jpountz]

Big +1.

[s1monw]

the one thing that we are loosing here is request timeouts here that we where able to put into the get(TimeValue) and friends calls. I think we can just put this on the request itself. Also if users want to have Future like classes that they can just collect I think we can provide a utility listener that allows you do to this.

[rjernst]

Sounds great to me! I've been bitten by not calling .get() more than once...

[bleskes]

+1. Looks like a good compromise between the alternatives.

[kimchy]

I like it!. I think that adding the timeout to the request itself will be misleading, since there users might think its a timeout on the call itself (like search timeout, that still returns values), compared to just giving up on the call completely (which is what the future does). In that context, I like the notion of future that also implements an ActionListener that someone can pass to the call and then work with it.

[s1monw]

ok cool it seems like we are sold here. I took a quick look at this and it's going to create a boat load of compile errors so I think the easiest path here is to do this over time and add one API a time and / or deprecate them? I'd like to start with this rather sooner than later since that way everybody can help when folks are idling etc?

[rjernst]

I'd like to start with this rather sooner than later since that way everybody can help when folks are idling etc?

+1

[jprante]

The API can be a bit confusing when mixed with blocking/non-blocking methods. It could even be more simplified with Observables, like in Couchbase http://docs.couchbase.com/developer/java-2.0/observables.html explained in this blog post http://blog.couchbase.com/why-couchbase-chose-rxjava-new-java-sdk

public interface ClusterAdminService ... {
    Observable<ClusterHealthResponse> health(ClusterHealthRequest request);

but that is for the time when ES is ready for Java 8 :)

[s1monw]

I actually wonder if it makes sense to seperate blocking and non-blocking API interface wise and just make one call another. that would mean 1 method per endpoint and clear distinction.