Thanks. I won't do it immediately - I appreciate the Open Source
nature and different people holding different opinions, and I
understand that not everyone can reply straight away. I'll hold back
and enable others to voice their thoughts if they wish.
Jon
On Tue, Jan 28, 2020 at 10:42 PM Markus KARG <markus@xxxxxxxxxxxxxxx
<mailto:markus@xxxxxxxxxxxxxxx>> wrote:
Feel free to provide a PR -- but note, what I wrote always is just
my personal opinion. As this is an open source project, there
certainly are other people having possibly different opinions.
-Markus
*Von:*jaxrs-dev-bounces@xxxxxxxxxxx
<mailto:jaxrs-dev-bounces@xxxxxxxxxxx>
[mailto:jaxrs-dev-bounces@xxxxxxxxxxx
<mailto:jaxrs-dev-bounces@xxxxxxxxxxx>] *Im Auftrag von *Jonathan
Gallimore
*Gesendet:* Dienstag, 28. Januar 2020 23:29
*An:* jaxrs developer discussions
*Betreff:* Re: [jaxrs-dev] Spec clarification: UriBuilder
> If you ask me, yes, we should remove these TCK-enforces support
for non-http schemas.
I'd agree, and I'm happy (keen, actually) to do that. Are you ok
for me to take a swing at that? If so, is there a specific process
you'd like me to follow (e.g. open a GitHub issue referencing this
thread)?
> But this does not solve the customers request. ;-)
When I used the word "consumer" I wasn't referring to a specific
customer. I meant consumer as in "something could consume this
API" (i.e. code). I do have a piece of code that does this, and
I'm sure it can be re-worked to use another mechanism. I simply
wanted to clarify whether UriBuilder *could* be used for this.
You've clarified that it absolutely should *not*, which is useful
- thank you.
Jon
On Tue, Jan 28, 2020 at 10:17 PM Markus KARG
<markus@xxxxxxxxxxxxxxx <mailto:markus@xxxxxxxxxxxxxxx>> wrote:
If you ask me, yes, we should remove these TCK-enforces
support for non-http schemas. But this does not solve the
customers request. ;-)
-Markus
*Von:*jaxrs-dev-bounces@xxxxxxxxxxx
<mailto:jaxrs-dev-bounces@xxxxxxxxxxx>
[mailto:jaxrs-dev-bounces@xxxxxxxxxxx
<mailto:jaxrs-dev-bounces@xxxxxxxxxxx>] *Im Auftrag von
*Jonathan Gallimore
*Gesendet:* Dienstag, 28. Januar 2020 23:16
*An:* jaxrs developer discussions
*Betreff:* Re: [jaxrs-dev] Spec clarification: UriBuilder
> 3. TCKs can have faults. In this case, design faults made by
people trying to provide more than actually intended. ;-)
Should we correct them?
Jon
On Tue, Jan 28, 2020 at 10:13 PM Markus KARG
<markus@xxxxxxxxxxxxxxx <mailto:markus@xxxxxxxxxxxxxxx>> wrote:
2. Because it is not needed. The spec is 100% clear. If we
have to copy the spec in the API, we could effectively
drop it. Don't get me wrong, that would actually be a good
idea. But either we do it completely or not at all. I do
not see why we should it do with just that single line
that you want in particular but not with all the rest.
3. TCKs can have faults. In this case, design faults made
by people trying to provide more than actually intended. ;-)
-Markus
*Von:*jaxrs-dev-bounces@xxxxxxxxxxx
<mailto:jaxrs-dev-bounces@xxxxxxxxxxx>
[mailto:jaxrs-dev-bounces@xxxxxxxxxxx
<mailto:jaxrs-dev-bounces@xxxxxxxxxxx>] *Im Auftrag von
*Jonathan Gallimore
*Gesendet:* Dienstag, 28. Januar 2020 23:00
*An:* jaxrs developer discussions
*Betreff:* Re: [jaxrs-dev] Spec clarification: UriBuilder
> 2. The JAX-RS spec consists of both, the spec text PLUS
the JavaDocs. It is a false assumption that the JavaDocs
must copy the spec. Your customer must read BOTH.
Is there a reason why a one-line sentence can't be added
to the Javadoc to provide additional clarification? It
seems like a couple of folks on this thread have mentioned it.
> 3. The TCK is not authoritative, only the Spec text PLUS
the JavaDocs is.
In order to be a compatible implementation, you *have* to
pass the TCK. The TCK, at the moment, has checks and
assertions for a number of non-http schemes. If an
implementation does not pass the TCK tests relating to
these, it isn't a compatible implementation.
Jon
On Tue, Jan 28, 2020 at 9:37 PM Markus KARG
<markus@xxxxxxxxxxxxxxx <mailto:markus@xxxxxxxxxxxxxxx>>
wrote:
JAX-RS is not a common purpose library. It serveres
exactly for the sole purpose of implementing or
calling RESTful WebServices over HTTP. This includes
100% of the classes and interfaces defined by it. All
other uses are out of scope of the specification.
Fullstop.
You customer hence clearly misuses the class as
apparently he is building an URI for a use outside of
JAX-RS. We talk about "javax.ws.rs.core.UriBuilder"
(hence a part of the JAX-RS kernel) not
"java.net.UriBuilder" (hence a part of Java's common
purpose networking subsystem). If your customer
doesn't understand the difference, please explain to
him the difference.
UriBuilder in particular does not contain any builder
methods for any parts of non-http schemas, so its
actual value is doubtful for non-http-schemas. For
example, there is no "password(String)" method to
build authenticated FTP URLs.
1. "The API" is all classes found in javax.ws.rs
<http://javax.ws.rs>. This certainly contains
UriBuilder. This IS obvious.
2. The JAX-RS spec consists of both, the spec text
PLUS the JavaDocs. It is a false assumption that the
JavaDocs must copy the spec. Your customer must read BOTH.
3. The TCK is not authoritative, only the Spec text
PLUS the JavaDocs is.
As 2.1 is 100% unambiguous there is no need for any
additional or copied clarification.
-Markus
*Von:*jaxrs-dev-bounces@xxxxxxxxxxx
<mailto:jaxrs-dev-bounces@xxxxxxxxxxx>
[mailto:jaxrs-dev-bounces@xxxxxxxxxxx
<mailto:jaxrs-dev-bounces@xxxxxxxxxxx>] *Im Auftrag
von *Jonathan Gallimore
*Gesendet:* Dienstag, 28. Januar 2020 21:48
*An:* jaxrs developer discussions
*Betreff:* Re: [jaxrs-dev] Spec clarification: UriBuilder
Hi
Thanks for all the great discussion around this, I
appreciate it. I'll give my 2 cents, if I may. I do
understand the point that the spec is describing REST
over HTTP, and hesitation to expand on UriBuilder
further for non-http schemes.
The reason for seeking clarification, unfortunately,
isn't theoretical. The spec provides UriBuilder, and
it can be used by a consumer anywhere the API and an
implementation is present. I'm in a position where I
have a consumer doing just that. I suspect that there
was a requirement to build a File URI, and the
developer found "UriBuilder" (IDE-auto complete
maybe?), saw it under a javax namespace (I appreciate
the package is changing in Jakarta EE 9), and thought
it was good to use for this purpose.
There's a couple of things I'd point out:
1. The spec documentation does state "The
specification will assume HTTP[bib4] is the underlying
network protocol and will provide a clear mapping
between HTTP and URI[bib5] elements and the
corresponding API classes and annotations."
2. The JavaDoc doesn't specifically call out the fact
that UriBuilder is only suitable for HTTP -
https://github.com/eclipse-ee4j/jaxrs-api/blob/master/jaxrs-api/src/main/java/jakarta/ws/rs/core/UriBuilder.java,
and references RFC 3986 which is much wider ranging
than HTTP
3. The TCK specifies tests for UriBuilder for other
schemes - for example:
https://github.com/eclipse-ee4j/jakartaee-tck/blob/master/src/com/sun/ts/tests/jaxrs/api/rs/core/uribuilder/JAXRSClient.java#L633-L638 includes:
mailto, urn, ldap, telnet and foo(!)
While point (1) is quite clear, it might not be
obvious that it applies to UriBuilder. Even if it is,
it appears to be contradictory to (2) and (3).
The file URI actually used to work in CXF. The change
that broke it, bizarrely, is a change to pass TCK
tests for other schemes (mailto, urn, ldap, telnet and
foo!). Side note - I have reported this to CXF, and
provided a patch. Some adjustments have been
requested, but I'm hopeful that if I make the
necessary changes, the fix will be merged in.
From a spec perspective, if the desire is for
UriBuilder to be http only, then I think that should
be called out in the Javadoc (and maybe more clearly
in the spec doc), and the assertions for non-http
schemes removed in the TCK. That would allow an
implementation of UriBuilder to support nothing but
http schemes and still pass the TCK. If the desire is
to allow support for non-http URI schemes, then I
think additional tests for UriBuilder.fromUri().path()
with a range of schemes is reasonable, and shouldn't
be too difficult to add. I doubt it'll have a big
impact on the current implementations. Given that
Jakarta EE 9 is mostly package rename, it might not
actually be until Jakarta EE 10 that the tests changes
would take effect.
Whichever way this ends up going, I do think there's
some genuine confusion, and need for clarification so
the spec doc, javadoc and TCK tests are in alignment.
I'm very happy to do the work and submit PRs (in fact
I would love the opportunity to do that).
Thank you again for all the discussion. I think
it's fantastic to see more of this in the open with
the move to Jakarta EE.
Jon
On Tue, Jan 28, 2020 at 7:33 PM Rob McDougall
<rob.mcdougall@xxxxxxxxxx
<mailto:rob.mcdougall@xxxxxxxxxx>> wrote:
Hi Markus,
Are you arguing that the UriBuilder class should
be renamed to HttpUriBuilder (since it can’t
possibly support all possible URIs and since it is
only really required to support http)?
I don’t think anyone is really arguing that
UriBuilder should or can support all possible
schemes, however I don’t think it’s unreasonable
for it to support some small number of known (and
common) schemes.
If I understand your point of view, you are
arguing that this small number (as mandated by the
JAX-RS spec) should be limited to http-related
schemes. I can understand the logic in that.
What is the harm in logging an enhancement request
with a specific implementation to support a very
slightly larger superset of the schemes mandated
by the spec? The Jersey team has already
undertaken the work for their implementation and I
wouldn’t imagine the work in supporting it in
other implementations is particularly onerous. I
can certainly see the benefit in supporting
file:// in addition to the http-related schemes.
Can’t you?
Regards,
Rob
Rob McDougall | Senior Technical Architect
|*4Point*| +1.613.907.6415 | www.4Point.com
<http://www.4point.com/>
Receive our news and announcements before anyone
else - follow us on:
Twitter icon - small
<https://twitter.com/4point_>linkedin icon - small
<https://www.linkedin.com/company-beta/843033/>Facebook
icon - small
<https://www.facebook.com/4PointSolutions/>
*From:*jaxrs-dev-bounces@xxxxxxxxxxx
<mailto:jaxrs-dev-bounces@xxxxxxxxxxx>
<jaxrs-dev-bounces@xxxxxxxxxxx
<mailto:jaxrs-dev-bounces@xxxxxxxxxxx>> *On Behalf
Of *Markus KARG
*Sent:* Tuesday, January 28, 2020 1:44 PM
*To:* 'jaxrs developer discussions'
<jaxrs-dev@xxxxxxxxxxx <mailto:jaxrs-dev@xxxxxxxxxxx>>
*Subject:* Re: [jaxrs-dev] Spec clarification:
UriBuilder
This could become complex given the fact that
UriBuilder is a *Builder* but URI can have
infinite schemas and each schema could have
infinite syntaxes, so how shall this effectively
work? And which vendor would be willing to
guarantee support for ANY kind of URI in their
existing product?
A general tool like this one should be part of
Java SE's URI support, not part of JAX-RS. And
again, chapter 1.2 mandates the _whole_ API's
charter, independent of what a particular class's
JavaDoc says.
-Markus
*Von:*jaxrs-dev-bounces@xxxxxxxxxxx
<mailto:jaxrs-dev-bounces@xxxxxxxxxxx>
[mailto:jaxrs-dev-bounces@xxxxxxxxxxx] *Im Auftrag
von *Christian Kaltepoth
*Gesendet:* Dienstag, 28. Januar 2020 08:51
*An:* jaxrs developer discussions
*Betreff:* Re: [jaxrs-dev] Spec clarification:
UriBuilder
I agree that JAX-RS of course focus on HTTP, but
UriBuilder is described as "URI template-aware
utility class for building URIs". And therefore I
would expect that it works with all kind of URIs.
I don't think that it is worth to add TCK tests
for it, but IMO this could/should be reported to
CXF as a bug.
Am Mo., 27. Jan. 2020 um 23:30 Uhr schrieb Markus
KARG <markus@xxxxxxxxxxxxxxx
<mailto:markus@xxxxxxxxxxxxxxx>>:
Jan,
I understand your point, but actually I doubt
that any implementing product actually would
support file:// URLs anywhere outside of
UriBuilder. JAX-RS cleary and explicitly is
solely http-centric:
1.2 Goals
The following are the goals of the API:
...
HTTP-centric The specification will assume
HTTP[4] is the underlying network protocol and
will provide a clear mapping between HTTP and
URI[5] elements and the corresponding API
classes and annotations. The API will provide
high level support for common HTTP usage
patterns and will be sufficiently flexible to
support a variety of HTTP applications
including WebDAV[6] and the Atom
Publishing Protocol[7].
...
So it wouldn't make much sense to force all
implementations to support file:// URLs in
UriBuilder if that is the sole place where
file:// would work then.
Just My 2C
-Markus
-----Ursprüngliche Nachricht-----
Von: jaxrs-dev-bounces@xxxxxxxxxxx
<mailto:jaxrs-dev-bounces@xxxxxxxxxxx>
[mailto:jaxrs-dev-bounces@xxxxxxxxxxx
<mailto:jaxrs-dev-bounces@xxxxxxxxxxx>] Im
Auftrag von Jan Supol
Gesendet: Montag, 27. Januar 2020 11:21
An: jaxrs-dev@xxxxxxxxxxx
<mailto:jaxrs-dev@xxxxxxxxxxx>
Betreff: Re: [jaxrs-dev] Spec clarification:
UriBuilder
Markus,
UriBuilder refers to RFC 3986. I was always
under the impression that
not only the HTTP scheme should be handled by
UriBuilder, but other
described by the RFC, too. Am I wrong?
Thanks,
Jan
On 24.01.2020 17:52, Markus KARG wrote:
>
> Well, UriBuilder is defined by JAX-RS, and
JAX-RS is an API for
> REST-/over-http/ only, so I doubt there will
be a cross-product
> solution be defined by us as long as you
want to use any other scheme
> than "http". ;-)
>
> -Markus
>
> *Von:*jaxrs-dev-bounces@xxxxxxxxxxx
<mailto:jaxrs-dev-bounces@xxxxxxxxxxx>
> [mailto:jaxrs-dev-bounces@xxxxxxxxxxx
<mailto:jaxrs-dev-bounces@xxxxxxxxxxx>] *Im
Auftrag von *Jonathan Gallimore
> *Gesendet:* Freitag, 24. Januar 2020 11:53
> *An:* jaxrs-dev@xxxxxxxxxxx
<mailto:jaxrs-dev@xxxxxxxxxxx>
> *Betreff:* [jaxrs-dev] Spec clarification:
UriBuilder
>
> Hi
>
> Hopefully this isn't daft question, but I'd
appreciate some help. I
> have a scenario where UriBuilder is being
used to construct a file
> URI, and append a path to it:
>
>
UriBuilder.fromUri("file:///~/calendar").path("extra").build().toString()
>
> I've tried this with a couple of
implementations, specifically Jersey
> and CXF, with differing results - Jersey
returns
> file:///~/calendar/extra, which is what I
personally would expect. CXF
> on the other hand picks up "///~/calendar"
as a "schemeSpecificPart"
> of the URI, and used that, and does not
append the path.
>
> I'm looking at
>
https://github.com/eclipse-ee4j/jakartaee-tck/blob/master/src/com/sun/ts/tests/jaxrs/api/rs/core/uribuilder/JAXRSClient.java
-
> its possible I've missed something, but I
can't see a case that
> specifically covers file://, or a case that
specifically covers
> UriBuilder.fromUri().path() (there are
others that test cases such as
> fromUri().port(), fromUri().host() and
fromUri().scheme() etc).
>
> Could you clarify what behaviour you'd
expect in this scenario, and /
> or point me at the relevant part of the spec
document (I'm struggling
> to find a reference there too).
>
> I'd be very happy to contribute any
appropriate updates to either
> documentation or TCK tests if necessary.
>
> Many thanks
>
> Jon
>
> --
>
> Jonathan Gallimore
>
> http://www.tomitribe.com
<http://www.tomitribe.com/>
>
>
> _______________________________________________
> jaxrs-dev mailing list
> jaxrs-dev@xxxxxxxxxxx
<mailto:jaxrs-dev@xxxxxxxxxxx>
> To change your delivery options, retrieve
your password, or unsubscribe from this list,
visit
>
https://www.eclipse.org/mailman/listinfo/jaxrs-dev
_______________________________________________
jaxrs-dev mailing list
jaxrs-dev@xxxxxxxxxxx
<mailto:jaxrs-dev@xxxxxxxxxxx>
To change your delivery options, retrieve your
password, or unsubscribe from this list, visit
https://www.eclipse.org/mailman/listinfo/jaxrs-dev
_______________________________________________
jaxrs-dev mailing list
jaxrs-dev@xxxxxxxxxxx
<mailto:jaxrs-dev@xxxxxxxxxxx>
To change your delivery options, retrieve your
password, or unsubscribe from this list, visit
https://www.eclipse.org/mailman/listinfo/jaxrs-dev
--
Christian Kaltepoth
Blog: http://blog.kaltepoth.de/
Twitter: http://twitter.com/chkal
GitHub: https://github.com/chkal
_______________________________________________
jaxrs-dev mailing list
jaxrs-dev@xxxxxxxxxxx <mailto:jaxrs-dev@xxxxxxxxxxx>
To change your delivery options, retrieve your
password, or unsubscribe from this list, visit
https://www.eclipse.org/mailman/listinfo/jaxrs-dev
--
Jonathan Gallimore
http://www.tomitribe.com <http://www.tomitribe.com/>
_______________________________________________
jaxrs-dev mailing list
jaxrs-dev@xxxxxxxxxxx <mailto:jaxrs-dev@xxxxxxxxxxx>
To change your delivery options, retrieve your
password, or unsubscribe from this list, visit
https://www.eclipse.org/mailman/listinfo/jaxrs-dev
--
Jonathan Gallimore
http://www.tomitribe.com <http://www.tomitribe.com/>
_______________________________________________
jaxrs-dev mailing list
jaxrs-dev@xxxxxxxxxxx <mailto:jaxrs-dev@xxxxxxxxxxx>
To change your delivery options, retrieve your password,
or unsubscribe from this list, visit
https://www.eclipse.org/mailman/listinfo/jaxrs-dev
--
Jonathan Gallimore
http://www.tomitribe.com <http://www.tomitribe.com/>
_______________________________________________
jaxrs-dev mailing list
jaxrs-dev@xxxxxxxxxxx <mailto:jaxrs-dev@xxxxxxxxxxx>
To change your delivery options, retrieve your password, or
unsubscribe from this list, visit
https://www.eclipse.org/mailman/listinfo/jaxrs-dev
--
Jonathan Gallimore
http://www.tomitribe.com <http://www.tomitribe.com/>
_______________________________________________
jaxrs-dev mailing list
jaxrs-dev@xxxxxxxxxxx <mailto:jaxrs-dev@xxxxxxxxxxx>
To change your delivery options, retrieve your password, or
unsubscribe from this list, visit
https://www.eclipse.org/mailman/listinfo/jaxrs-dev
--
Jonathan Gallimore
http://www.tomitribe.com <http://www.tomitribe.com/>
_______________________________________________
jaxrs-dev mailing list
jaxrs-dev@xxxxxxxxxxx
To change your delivery options, retrieve your password, or unsubscribe from this list, visit
https://www.eclipse.org/mailman/listinfo/jaxrs-dev
