jax-rs-spec
  1. jax-rs-spec
  2. JAX_RS_SPEC-398

UriInfo.relativize javadoc shows invalid example

    Details

    • Type: Bug Bug
    • Status: Resolved
    • Priority: Major Major
    • Resolution: Fixed
    • Affects Version/s: 2.0
    • Fix Version/s: 2.0
    • Component/s: spec
    • Labels:
      None

      Description

      Note: This issue was previously posted as JAX_RS_SPEC-398 which somehow disappeared. I was requested to post it again - see

      In the documentation https://jax-rs-spec.java.net/nonav/2.0-SNAPSHOT/apidocs/javax/ws/rs/core/UriInfo.html#relativize(java.net.URI)

      The example is misleading (and wrong):

      Examples (for base URI http://host:port/app/root/):

      Request URI: http://host:port/app/root/a/b/c
      Supplied URI: a/b/c/d/e
      Returned URI: d/e

      But this would be an invalid example, as trying to resolve the returned URI shows:

      java.net.URI.create("http://host:port/app/root/a/b/c").resolve("d/e")
      http://host:port/app/root/a/b/d/e
      

      This is simply because a / is missing at the end of the request URI - it would be very strange for someone requesting /app/root/a/b/c to interpret that as /app/root/a/b/c/. Replace "c" with "index.html" to understand in a web sense, it's reference to d.png should not resolve to index.html/d.png.

      The above misleading example has already led to confusions in the implementation in CXF - see https://issues.apache.org/jira/browse/CXF-4919 – in my suggested patch I have deliberately changed the original test to not check for the specified behaviour in JAX-RS javadocs as I believe it is wrong.

      The documentation could probably be rewritten to use a .html resource to be more understandable out of the box. I would also change the confusing (and HTTP-wise invalid) ":port" - as this is an example no need to be generic

      For instance:

      Base URI: http://example.com:8080/app/root/
      Request URI: http://example.com:8080/app/root/a/b/c/resource.html
      Supplied URI: a/b/c/d/e.txt
      Returned URI: d/e.txt

      Or a very simpler fix would be to just add the missing / in the request URI:

      Examples (for base URI http://host:port/app/root/):

      Request URI: http://host:port/app/root/a/b/c/
      Supplied URI: a/b/c/d/e
      Returned URI: d/e

      .. although that would still lead open to the same confusions for request URIs not ending in /.

        Activity

        stain created issue -
        Hide
        beryozkin_sergey added a comment -

        Indeed, u.resolve(u.relativize(v)).equals(v) (from the URI documentation) does not work without the last "/", should be "http://host:port/app/root/a/b/c/"

        Show
        beryozkin_sergey added a comment - Indeed, u.resolve(u.relativize(v)).equals(v) (from the URI documentation) does not work without the last "/", should be "http://host:port/app/root/a/b/c/"
        beryozkin_sergey made changes -
        Field Original Value New Value
        Assignee Santiago Pericas-Geertsen [ spericas ]
        Fix Version/s 2.1 [ 16402 ]
        Hide
        Marek Potociar added a comment -

        Example updated in the final release bits.

        Show
        Marek Potociar added a comment - Example updated in the final release bits.
        Marek Potociar made changes -
        Status Open [ 1 ] Resolved [ 5 ]
        Fix Version/s 2.0 [ 14715 ]
        Fix Version/s 2.1 [ 16402 ]
        Resolution Fixed [ 1 ]

          People

          • Assignee:
            Santiago Pericas-Geertsen
            Reporter:
            stain
          • Votes:
            0 Vote for this issue
            Watchers:
            0 Start watching this issue

            Dates

            • Created:
              Updated:
              Resolved: