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

Some of UriBuilder resolveTemplate methods do not fit into UriBuilder build style

    Details

    • Type: Improvement Improvement
    • Status: Closed
    • Priority: Major Major
    • Resolution: Works as designed
    • Affects Version/s: None
    • Fix Version/s: 2.0
    • Component/s: model api, spec
    • Labels:
      None

      Description

      UriBuilder style is about accumulating the state and then doing a build with one of the build() or buildFromEncoded() methods.

      For example, one can request that URI is built with the assumption that all template vars have already been encoded (buildFromEncoded) or that path variable values containing a slash have to be encoded (build() accepting an encodePathSlash parameter).

      The introduction of resolveTemplateFromEncoded() and resolveTemplate() accepting encodePathSlash makes the existing style involving build() methods less consistent. For example, resolveTemplate() accepting encodePathSlash may be followed by the build method providing the opposite encodePathSlash value.

      Similarly, the same applies to a new builder method, toTemplate(). One can have resolveTemplate() accepting encodePathSlash called a number of times with different encodePathSlash values and it will not be obvious at toTemplate() time which path variables have to be treated specifically and which not.

      The above may seem like a very minor issue - but IMHO the core API construct such as UriBuilder should not have any space for the ambiguity.

      For example, arguably, a support for encoding path slashes could've been implemented differently to having a build() method accepting 'encodePathSlash'. But the current solution fits into the UriBuilder build style, specifically, the decision to customize is done at the final build step.

      Thus I propose to optimize a bit the way resolveTemplates support is done.

      At the bare minimum: remove resolveTemplates accepting encodePathSlash - this is already covered by a related build method; to get the same supported at the toTemplate() level do add a new toTemplate(boolean encodePathSlash) method or modify the existing one.

      Next, unless a support for having a combination for already-encoded and not yet encoded template var values is absolutely required, repeat the same process for resolveTemplatesFromEncoded - drop them and introduce a related toTemplate method

      IMHO - this will make UriBuilder API and quite minimalistic again

        Activity

        Hide
        Marek Potociar added a comment -

        -1 on the proposal.

        UriBuilder.resolveTemplate() causes the underlying URI builder template to change based on supplied value. The change is IMMEDIATE. If you decided to defer the change to the time when a toTemplate() is called, it's your implementation detail and you need to deal with it in your impl. As such we need a mechanism for controlling the encoding of resolution value(s) in the same way we do it when we use the template to build final URI in build() methods. The current API provides the mechanism. Also with the immediate change there should no confusion about mixing the encoding values in subsequent resolveTemplate invocation calls.

        Show
        Marek Potociar added a comment - -1 on the proposal. UriBuilder.resolveTemplate() causes the underlying URI builder template to change based on supplied value. The change is IMMEDIATE. If you decided to defer the change to the time when a toTemplate() is called, it's your implementation detail and you need to deal with it in your impl. As such we need a mechanism for controlling the encoding of resolution value(s) in the same way we do it when we use the template to build final URI in build() methods. The current API provides the mechanism. Also with the immediate change there should no confusion about mixing the encoding values in subsequent resolveTemplate invocation calls.
        Hide
        Marek Potociar added a comment -

        Closing as agreed in EG.

        Show
        Marek Potociar added a comment - Closing as agreed in EG.

          People

          • Assignee:
            Marek Potociar
            Reporter:
            beryozkin_sergey
          • Votes:
            0 Vote for this issue
            Watchers:
            0 Start watching this issue

            Dates

            • Created:
              Updated:
              Resolved: