Let me assure you that despite the changes in the spec schedule plan, we (Oracle) do not choose the schedule dates randomly. When doing the planning for JAX-RS we need to look at Java EE 7 schedule and taking into account all the JCP required periods and potential inter-spec dependencies we arrive at some schedule dates we simply MUST meet if we do not want to cause a slip of the whole Java EE 7.
Now I know that Java EE 7 release plans have changed recently and we might have gained some more room for our schedule. But any changes in the already approved JAX-RS schedule still need to be discussed with the Java EE umbrella spec leads and management team. We're currently in the process of doing so. And until any change is approved, the current schedule is what we need to comply with.
(Btw. we can still make changes after PR date. But I'd like to keep those at a reasonable minimum if possible.)
On Sep 6, 2012, at 6:16 PM, Markus KARG <markus_at_headcrashing.eu> wrote:
> Side comment: I think it will be no good idea to fix the PR by date instead of by content. Making stress just for the sake of a totally randomly chosen date is no good thing. While it got rather popular in the past months in some Oracle-led JSRs (e. g. Java SE 8 without Jigsaw, Java EE 8 without Cloud Support), I do not think that we should go that track in general. If you need more time to fix more API details, simply move the PR date.
>
> From: Marek Potociar [mailto:marek.potociar_at_oracle.com]
> Sent: Donnerstag, 6. September 2012 17:53
> To: jsr339-experts_at_jax-rs-spec.java.net
> Subject: [jsr339-experts] Re: [jax-rs-spec users] Re: PLEASE READ: Resolving UriBuilder / WebTarget templates
>
> Ok, thanks for support. To clarify - the urgency comes from the fact that I'd like to make the change before we release PR version of the API.
>
> Marek
>
> On Sep 6, 2012, at 4:48 PM, Markus KARG <markus_at_headcrashing.eu> wrote:
>
>
> While I do not see the urgent need for the proposed solution as I do not see the urgent problem, I agree with your proposal.
>
> From: Marek Potociar [mailto:marek.potociar_at_oracle.com]
> Sent: Donnerstag, 6. September 2012 16:10
> To: jsr339-experts_at_jax-rs-spec.java.net
> Subject: [jsr339-experts] PLEASE READ: Resolving UriBuilder / WebTarget templates
>
> Hello experts,
>
> I know it's a long email, but please bear with me. I'd like to propose some changes to the WebTarget and UriBuilder API. Following email provides the rationale as well as the proposal.
>
> Currently we have following methods in the WebTarget:
>
> pathParam(String name, Object value)
> pathParams(Map<String, Object> parameters)
>
> Their purpose is to set values to path template variables. E.g.:
>
> client.target("{a}/{b}").pathParam("a", "x") --> "x/{b}"
>
> Also, we have a couple of requests in Jira to provide similar functionality in UriBuilder as well as in general resolve the inconsistencies between WebTarget andUriBuilder URI building API:
>
> http://java.net/jira/browse/JAX_RS_SPEC-211
> http://java.net/jira/browse/JAX_RS_SPEC-163
>
> Also there is a Jersey issue filed around inconsistencies/confusion of what WebTarget.getUriBuilder() should return:
>
> http://java.net/jira/browse/JERSEY-1329
>
> So while looking at the WebTarget/UriBuilder consolidation from the larger perspective provided by all these issues, I'd like to propose some changes in these APIs.
>
> First of all, WebTarget.pathParam(s) are misleading method names, since the actual intended purpose of the methods was to resolve a template variable to a value. IOW the expected behavior is:
>
> client.target("{a}").path("{b}").queryParam("a", "{a}").pathParam("a", "x") --> "x/{b}?a=x"
>
> Now I think you're with me, when I say that the name of the pathParam method is misleading. Another issue, perhaps even more interesting is finding the right answer for a question on what should WebTarget.getUriBuilder() return - how should the returned UriBuilder be initialized. For example:
>
> client.target("{a}/{b}").pathParam("a", "x").getUriBuilder()
>
> In this case a few answers are possible for the internal state of the returned UriBuilder:
>
> URI template: "{a}/{b}", internal template values: N/A
> URI template: "{a}/{b}", internal template values: "a" -> "x"
> URI template: "x/{b}", internal template values: N/A
>
> Now after a careful consideration, I'd argue that we should take approach that corresponds to the answer #3 (even though it may not seem to be the most intuitive answer). IOW, I could not find any practical use case that would support the other 2 options and could not be solvable by 3, but I could find use cases that would only be solvable by #3. One other indication might be that it's hard to find a use case where following makes sense and could be considered as a good practice:
>
> client.target("{a}/{b}").pathParam("a", "x")...pathParam("a", "y")
>
> So my conclusion is that typically you only set a template value only once and once you set it you do want to overwrite it later. E.g.:
>
> authors = client.target("bookstore/authors/{name}");
> author = authors.pathParam("name", "Dan Ariely");
>
> ... /* somewhere in a different part of app */ ...
>
> books = author.path("books/{name}");
> book = books.pathParam("name", "Predictably Irrational");
>
> In the code above the issue with overwriting template values set before is obvious. You certainly do not want to overwrite the author's name with the name of the book.
>
> So finally, here comes my proposal:
>
> remove WebTarget.pathParam(s) methods
> introduce new WebTarget.resolveTemplate(s) methods, including method versions that provide flag for "/" encoding in path
> introduce new UriBuilder.resolveTemplate(s) methods, including method versions that provide flag for "/" encoding in path
>
> The new resolveTemplate(s) methods would irreversibly resolve the template values in WebTarget or UriBuilder for given template variables, e.g.:
>
> client.target("{a}/{b}").resolveTemplate("a", "x").resolveTemplate("a", "y") --> "x/{b}"
> // resolveTemplate("a", "y") above is either ignored or throws IllegalStateException
>
> This proposal should make things consistent. Please provide your feedback ASAP. I'd like to make this change before the PR release planned for next Monday.
>
> Thank you,
> Marek
>
>