portletspec3
  1. portletspec3
  2. PORTLETSPEC3-9

Errata: Clarification needed for method MimeResponse.createRenderURL

    Details

      Description

      The description contains a statement that I believe to be incorrect. It states:

      "The created URL will per default not contain any parameters of the current render request."

      However, the created URL I believe must contain any public render parameters that were set on
      the request. Also, the term "current render request" may be misleading. What is meant is the
      request that is being executed when the URL is created.

      So I would propose the following update:

      Original:
      -------------------------
      createRenderURL

      PortletURL createRenderURL()

      Creates a portlet URL targeting the portlet. If no portlet mode, window state or security modifier is set in the PortletURL the current values are preserved. If a request is triggered by the PortletURL, it results in a render request.

      The returned URL can be further extended by adding portlet-specific parameters and portlet modes and window states.

      The created URL will per default not contain any parameters of the current render request.

      Returns:
      a portlet render URL
      -------------------------

      Corrected:
      -------------------------
      createRenderURL

      PortletURL createRenderURL()

      Creates a portlet URL targeting the portlet. If no portlet mode, window state or security modifier is set in the PortletURL the current values are preserved. If a request is triggered by the PortletURL, it results in a render request.

      The returned URL can be further extended by adding portlet-specific parameters and portlet modes and window states.

      The created URL will per default contain only the public render parameters from the request
      being executed when the render URL is created.

      Returns:
      a portlet render URL
      -------------------------

      The same change should be made for the MimeResponse.createActionURL method.

        Activity

        Hide
        msnicklous added a comment -

        Updated the description to address the "current render request" aspect.

        Show
        msnicklous added a comment - Updated the description to address the "current render request" aspect.
        Hide
        Neil Griffin added a comment -

        I determined that Liferay's portlet container currently implements the existing requirement, meaning that the result of MimeResponse.createRenderURL() does "not contain any parameters of the current render request"

        However, Pluto does not implement the existing requirement. Instead, it implements the proposed change such that it contains "only the public render parameters from the request being executed when the render URL is created"

        The proposed changed would have almost no impact on JSF 2 portlets, since they rarely make use of render URLs.

        It might have more impact on Java/JSP based portlets, where developers tend to use <portlet:renderURL /> somewhat regularly.

        Does the portlet developer want the public render parameters to continue getting propagated? I can see a case for both yes and no. I guess it depends on what we consider the main use-case to be.

        Show
        Neil Griffin added a comment - I determined that Liferay's portlet container currently implements the existing requirement, meaning that the result of MimeResponse.createRenderURL() does "not contain any parameters of the current render request" However, Pluto does not implement the existing requirement. Instead, it implements the proposed change such that it contains "only the public render parameters from the request being executed when the render URL is created" The proposed changed would have almost no impact on JSF 2 portlets, since they rarely make use of render URLs. It might have more impact on Java/JSP based portlets, where developers tend to use <portlet:renderURL /> somewhat regularly. Does the portlet developer want the public render parameters to continue getting propagated? I can see a case for both yes and no. I guess it depends on what we consider the main use-case to be.
        Show
        Neil Griffin added a comment - Test Portlet: https://github.com/ngriffin7a/portletbox/tree/master/issues/PORTLETSPEC3-9-portlet
        Hide
        rossclewley added a comment -

        I've tried Neil's test portlet on the Oracle portlet container and it implements the current requirement that MimeResponse.createRenderURL() does "not contain any parameters of the current render request". i.e. the same as Liferay.

        Show
        rossclewley added a comment - I've tried Neil's test portlet on the Oracle portlet container and it implements the current requirement that MimeResponse.createRenderURL() does "not contain any parameters of the current render request". i.e. the same as Liferay.
        Hide
        msnicklous added a comment -

        I propose the following changes to the javadoc descriptions of the createRenderURL, createActionURL, and createResourceURL methods on the MimeResponse class:

        PortletURL createRenderURL()

        Creates a portlet URL targeting the portlet. If no portlet mode, window state or security modifier is set in the PortletURL the current values are preserved. If a request is triggered by the PortletURL, it results in a render request.

        The new render URL will not contain any private render parameters from the current request.

        The returned URL can be further extended by adding portlet-specific render parameters and portlet modes and window states. Any parameter added to the render URL is automatically a render parameter.

        Public render parameters do not need to be explicitly added to the new render URL, unless the public render parameter value is to be changed. Any public render parameters associated with the portlet will automatically be available during render request processing resulting from activation of the URL.

        If a public render parameter value is changed on a render URL, then the public render parameter will be set to the new value when the URL is activated.

        Returns:
        a portlet render URL

        PortletURL createActionURL()

        Creates a portlet URL targeting the portlet. If no portlet mode, window state or security modifier is set in the PortletURL the current values are preserved. If a request is triggered by the PortletURL, it results in an action request.

        The new action URL will not contain any private render parameters from the current request.

        The returned URL can be further extended by adding portlet-specific action parameters and portlet modes and window states. Any parameter added to the action URL is automatically an action parameter.

        Public render parameters do not need to be explicitly added to the new action URL. Any public render parameters associated with the portlet will automatically be available during action request processing resulting from activation of the URL.

        If an action parameter has the same name as a public render parameter, then both the action parameter value(s) and the render parameter value(s) will be available when the action request is triggered. The action parameter value(s) will appear before the render parameter value(s) in the parameter values array.

        Returns:
        a portlet action URL

        ResourceURL createResourceURL()

        Creates a resource URL targeting the portlet. If no security modifier is set in the ResourceURL the current values are preserved. The current render parameters, portlet mode and window state are preserved depending on the cacheability setting for the new resource URL.

        If a request is triggered by the ResourceURL, it results in a serve resource request of the ResourceServingPortlet interface.

        If cacheability is set to PORTLET or PAGE, the values of the render parameters are preserved. Otherwise, the render parameters will not be preserved.

        The public and private render parameters are added to the URL with their current value. The render parameter values cannot be changed on the URL.

        The returned URL can be further extended by adding portlet-specific resource parameters. Any parameter added to the resource URL is automatically a resource parameter. If a resource parameter has the same name as a public or private render parameter, then both the resource parameter values and the render parameter values will be available when the resource request is triggered. The resource parameter value(s) will appear before the render parameter value(s) in the parameter values array.

        The created URL will contain the current cacheability setting of the parent resource by default. If no parent resource is available, PAGE is the default.

        Returns:
        a portlet resource URL

        Show
        msnicklous added a comment - I propose the following changes to the javadoc descriptions of the createRenderURL, createActionURL, and createResourceURL methods on the MimeResponse class: PortletURL createRenderURL() Creates a portlet URL targeting the portlet. If no portlet mode, window state or security modifier is set in the PortletURL the current values are preserved. If a request is triggered by the PortletURL, it results in a render request. The new render URL will not contain any private render parameters from the current request. The returned URL can be further extended by adding portlet-specific render parameters and portlet modes and window states. Any parameter added to the render URL is automatically a render parameter. Public render parameters do not need to be explicitly added to the new render URL, unless the public render parameter value is to be changed. Any public render parameters associated with the portlet will automatically be available during render request processing resulting from activation of the URL. If a public render parameter value is changed on a render URL, then the public render parameter will be set to the new value when the URL is activated. Returns: a portlet render URL PortletURL createActionURL() Creates a portlet URL targeting the portlet. If no portlet mode, window state or security modifier is set in the PortletURL the current values are preserved. If a request is triggered by the PortletURL, it results in an action request. The new action URL will not contain any private render parameters from the current request. The returned URL can be further extended by adding portlet-specific action parameters and portlet modes and window states. Any parameter added to the action URL is automatically an action parameter. Public render parameters do not need to be explicitly added to the new action URL. Any public render parameters associated with the portlet will automatically be available during action request processing resulting from activation of the URL. If an action parameter has the same name as a public render parameter, then both the action parameter value(s) and the render parameter value(s) will be available when the action request is triggered. The action parameter value(s) will appear before the render parameter value(s) in the parameter values array. Returns: a portlet action URL ResourceURL createResourceURL() Creates a resource URL targeting the portlet. If no security modifier is set in the ResourceURL the current values are preserved. The current render parameters, portlet mode and window state are preserved depending on the cacheability setting for the new resource URL. If a request is triggered by the ResourceURL, it results in a serve resource request of the ResourceServingPortlet interface. If cacheability is set to PORTLET or PAGE, the values of the render parameters are preserved. Otherwise, the render parameters will not be preserved. The public and private render parameters are added to the URL with their current value. The render parameter values cannot be changed on the URL. The returned URL can be further extended by adding portlet-specific resource parameters. Any parameter added to the resource URL is automatically a resource parameter. If a resource parameter has the same name as a public or private render parameter, then both the resource parameter values and the render parameter values will be available when the resource request is triggered. The resource parameter value(s) will appear before the render parameter value(s) in the parameter values array. The created URL will contain the current cacheability setting of the parent resource by default. If no parent resource is available, PAGE is the default. Returns: a portlet resource URL
        Hide
        Neil Griffin added a comment -

        Recommend using either "The new" or "The returned" in a consistent manner. Currently both terms are used very close together, though they refer to the same thing.

        Also, the general term "render parameter" is meaningful when it refers to either Public/Private Render Parameters that the portlet developer has explicitly set via StateAwareResponse.setRenderParameter(String name, String value). These are parameters that are set in the ACTION_PHASE/EVENT_PHASE and intended to survive into the RENDER_PHASE.

        However I think that the general term "render parameters" becomes vague/ambiguous when referring to parameters set on a URL. While it is true that a Public Render Parameter can be set on a URL, I don't think we can precisely say Private Render Parameters can be set on a URL. Rather, they are simply Private Parameters (not Private Render Parameters) when set on a URL.

        Because of this, I would recommend that the following sentence be clarified or perhaps not added:

        Any parameter added to the render URL is automatically a render parameter.

        Show
        Neil Griffin added a comment - Recommend using either "The new" or "The returned" in a consistent manner. Currently both terms are used very close together, though they refer to the same thing. Also, the general term "render parameter" is meaningful when it refers to either Public/Private Render Parameters that the portlet developer has explicitly set via StateAwareResponse.setRenderParameter(String name, String value). These are parameters that are set in the ACTION_PHASE/EVENT_PHASE and intended to survive into the RENDER_PHASE. However I think that the general term "render parameters" becomes vague/ambiguous when referring to parameters set on a URL. While it is true that a Public Render Parameter can be set on a URL, I don't think we can precisely say Private Render Parameters can be set on a URL. Rather, they are simply Private Parameters (not Private Render Parameters) when set on a URL. Because of this, I would recommend that the following sentence be clarified or perhaps not added: Any parameter added to the render URL is automatically a render parameter.
        Hide
        msnicklous added a comment -

        Hi Neil,

        I tried to be precise in my use of the term "render parameter" - that's (supposed to be) part of the actual clarification. I believe that parameters set on a render URL are actually render parameters, since clicking on a render URL will result in a render request. In the descriptions of createActionURL & createResourceURL, I used the terms "action parameters" and "resource parameters" correspondingly.

        Show
        msnicklous added a comment - Hi Neil, I tried to be precise in my use of the term "render parameter" - that's (supposed to be) part of the actual clarification. I believe that parameters set on a render URL are actually render parameters, since clicking on a render URL will result in a render request. In the descriptions of createActionURL & createResourceURL, I used the terms "action parameters" and "resource parameters" correspondingly.
        Hide
        msnicklous added a comment -

        Updated Javadoc comments on URL creation methods in MimeResponse.

        Show
        msnicklous added a comment - Updated Javadoc comments on URL creation methods in MimeResponse.
        Hide
        Neil Griffin added a comment -

        @Scott: Thanks for the clarification. Sounds good.

        Show
        Neil Griffin added a comment - @Scott: Thanks for the clarification. Sounds good.
        Hide
        msnicklous added a comment -

        changes reviewed on 6 Aug 2013

        Show
        msnicklous added a comment - changes reviewed on 6 Aug 2013

          People

          • Assignee:
            msnicklous
            Reporter:
            msnicklous
          • Votes:
            0 Vote for this issue
            Watchers:
            0 Start watching this issue

            Dates

            • Created:
              Updated:
              Resolved: