You got me wrong. With "randomly" I didn't meant "without any kind of
planning", but the sole fact that there is absolutely no *technical* reason
that Java EE 7 must be published on *any* fixed date -- nobody has any real
problem if Java EE 7 is done a week or two later. In fact, what I'd wanted
to say is that I'd prefer the Debian planning style ("It's done when it's
done") unless there is an arguable demand for a particular fixed date.
From: Marek Potociar [mailto:marek.potociar_at_oracle.com]
Sent: Donnerstag, 6. September 2012 19:18
To: jsr339-experts_at_jax-rs-spec.java.net
Subject: [jsr339-experts] Re: [jax-rs-spec users] Re: Re: PLEASE READ:
Resolving UriBuilder / WebTarget templates
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@ <
http://oracle.com> oracle.com]
Sent: Donnerstag, 6. September 2012 17:53
To: <mailto:jsr339-experts_at_jax-rs-spec.java.net>
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 < <mailto:markus_at_headcrashing.eu>
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@ <
http://oracle.com> oracle.com]
Sent: Donnerstag, 6. September 2012 16:10
To: <mailto:jsr339-experts_at_jax-rs-spec.java.net>
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-211
<
http://java.net/jira/browse/JAX_RS_SPEC-163>
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>
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:
1. URI template: "{a}/{b}", internal template values: N/A
2. URI template: "{a}/{b}", internal template values: "a" -> "x"
3. 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