Provide an "escape hatch" from WebTargetHelper

[sleberknight]

Discussed in #599

^{Originally posted by sleberknight August 25, 2021}
I just came across some code in our of our services which is using the JAX/Jakarta-RS WebTarget, and which could have used kiwi's WebTargetHelper. Basically, the code has a method that accepts a WebTarget and a Map<String, Object> of query parameters. It adds the given query parameters and returns a new WebTarget using code similar to what we've already written and put in WebTargetHelper.

So, in theory this code could easily have used WebTarget#queryParamsFromMap except that the method in the service returns a WebTarget while queryParamsFromMap returns a WebTargetHelper for method chaining purposes.

The problem is that there is no easy "escape hatch" from WebTargetHelper to simply return the current WebTarget. Since this method described above is intended to simply add query parameters to any WebTarget and return the new WebTarget with those parameters added, and then let the caller do whatever it likes, this won't work.

So the question is whether we should provide an "escape hatch" to permit this use case. Example code:

// This is what the utility method looked like:
static WebTarget targetWithQueryParams(WebTarget webTarget, Map<String, Object> parameters) {
   // ...bunch of code to create a new WebTarget with the query parameters added
  return newTarget;
}

We'd like to change it to use queryParamsFromMap like this:

static WebTarget targetWithQueryParams(WebTarget webTarget, Map<String, Object> parameters) {
   // if we had an "escape hatch" we could do something like
   return WebTargetHelper.withWebTarget(webTarget).queryParamsFromMap(parameters).escape();
}

WebTargetHelper actually does have an "escape hatch" method named wrapped() which returns a WebTarget, but it is currently package-private. One easy option is to simply make it public. Does this make sense? Is wrapped() a good name for the escape hatch, or is there a better name?