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. 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] 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." 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. 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 
Receive our news and announcements before anyone else - follow us on:   
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 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. 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] Im Auftrag von Jan Supol
Gesendet: Montag, 27. Januar 2020 11:21
An: 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] *Im Auftrag von *Jonathan Gallimore
> *Gesendet:* Freitag, 24. Januar 2020 11:53
> *An:* 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
> 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
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
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
To change your delivery options, retrieve your password, or unsubscribe from this list, visit
https://www.eclipse.org/mailman/listinfo/jaxrs-dev
-- |
