Fixes #4808 - Review HttpClient Request header APIs.

[sbordet]

Introduced:

• Request Request.headers(Consumer<HttpFields.Mutable>).
  This allows applications to modify the headers, and chain calls.
  It also delegates the precise semantic of put/add/remove/clear to HttpFields, so there is no API duplication.

• HttpRequest.header(HttpField) to efficiently add fields while normalizing the request (only used in implementation).

• HttpResponse.header(HttpField) to efficiently add fields while parsing the response (only used in implementation).
  This pairs with HttpResponse.trailer(HttpField).

• HttpResponse.headers(Consumer<HttpFields.Mutable>) to modify the fields after they have been populated (only used in tests).

Removed:

• Request.[set,add,put,remove], replaced by headers(Consumer<HttpFields.Mutable>).

Deprecated:

• Request.header(String, String)
• Request.header(HttpHeader, String)
  Both replaced by headers(Consumer<HttpFields.Mutable>) with clearer semantic for add/put/remove.

All the rest is code cleanup to remove the usage of the deprecated header() methods.

Signed-off-by: Simone Bordet simone.bordet@gmail.com

[lorban]

I really like the overall idea of concentrating all the HTTP field modification API into a single class, but it should be pushed to its full extent then: only have one single way to mutate HTTP fields: the lambda-taking mutating method headers().

This would have the extra bonus of making it cheap to extend the API with nice helper method (addIfAbsent, addIfNotNull...) that would make calling the lambda-taking mutating method very elegant to use.

[joakime]

Is the new headers() lambda applied after the Request.Content based content-types are applied?
Or in fact after any "default" headers are added?

That would allow someone to remove/change a header that is added by other processes in the request before it's sent.

[joakime]

Will you update the client documentation in a future commit?

[sbordet]

@joakime the lambda is invoke immediately.
What client documentation needs to be updated? The code snippets already are.

[lorban]

LGTM