portletspec3
  1. portletspec3
  2. PORTLETSPEC3-3

Errata: Clarification in Javadoc for CacheControl.getExpirationTime()

    Details

      Description

      In the Javadoc for the CacheControl class, the following is stated for getExpirationTime() and setExpirationTime().
      Taken together, it's a bit unclear as to what a return value of 0 from getExpirationTime() actually means - does
      it mean "hasn't been set" or does it mean "disabled"?

      The description for getExpirationTime() should be changed as indicated. The description for setExpirationTime() would remain unchanged.

      Original:
      -------------------------
      getExpirationTime
      
      int getExpirationTime()
      
          Get the currently set expiration time. If no expiration time is set on this response 
          the default defined in the portlet deployment descriptor with the expiration-cache 
          tag is returned, or 0 if no default is defined.
      
          This call returns the same value as the getProperty(EXPIRATION_CACHE) call.
      
          Returns:
              the currently set expiration time in seconds, or 0 if no expiration time is set.
      
      setExpirationTime
      
      void setExpirationTime(int time)
      
          Sets a new expiration time for the current response in seconds.
      
          If the expiration value is set to 0, caching is disabled for this portlet; 
          if the value is set to -1, the cache does not expire.
      
          This call is equivalent to calling setProperty(EXPIRATION_CACHE).
      
          Parameters:
              time - expiration time in seconds
      -------------------------
      
      Corrected:
      -------------------------
      getExpirationTime
      
      int getExpirationTime()
      
          Get the currently set expiration time. If no expiration time has been 
          explicitly set on this response, the default defined in the portlet 
          deployment descriptor with the expiration-cache tag is returned; If
          no default value is provided in the portlet deployment descriptor, 
          0 is returned.
      
          This call returns the same value as the getProperty(EXPIRATION_CACHE) call.
      
          Returns:
              the currently set expiration time in seconds; 
              0 indicates caching is disabled for this portlet; 
              -1 indicates the cache does not expire.
      
      setExpirationTime
      
      (unchanged)
      -------------------------
      

        Activity

        msnicklous created issue -
        Hide
        mfreedma added a comment -

        So though I think the structure of the sentence in the description improves/clarifies the meaning I am worried that changing the statement to "0 is assumed" is ambiguous/confusing. Since we are describing what value is returned, shouldn't we use the term returned instead of assumed?

        The changes to the description in the "returns" section is am improvement.

        Show
        mfreedma added a comment - So though I think the structure of the sentence in the description improves/clarifies the meaning I am worried that changing the statement to "0 is assumed" is ambiguous/confusing. Since we are describing what value is returned, shouldn't we use the term returned instead of assumed? The changes to the description in the "returns" section is am improvement.
        Hide
        Neil Griffin added a comment -

        I agree with Mike – "if no default is provided in the portlet deployment descriptor, 0 is returned."

        Show
        Neil Griffin added a comment - I agree with Mike – "if no default is provided in the portlet deployment descriptor, 0 is returned."
        Hide
        msnicklous added a comment -

        I agree with Mike & Neil ... I think we should use the sentence Neil suggested.

        Show
        msnicklous added a comment - I agree with Mike & Neil ... I think we should use the sentence Neil suggested.
        Hide
        msnicklous added a comment -

        updated formatting; incorporated suggested text change.

        Show
        msnicklous added a comment - updated formatting; incorporated suggested text change.
        msnicklous made changes -
        Field Original Value New Value
        Description In the Javadoc for the CacheControl class, the following is stated for getExpirationTime() and setExpirationTime().
        Taken together, it's a bit unclear as to what a return value of 0 from getExpirationTime() actually means - does
        it mean "hasn't been set" or does it mean "disabled"?

        The description for getExpirationTime() should be changed as indicated. The description for setExpirationTime() would remain unchanged.

        Original:
        -------------------------
        getExpirationTime

        int getExpirationTime()

            Get the currently set expiration time. If no expiration time is set on this response
            the default defined in the portlet deployment descriptor with the expiration-cache tag is returned, or 0 if no default is defined.

            This call returns the same value as the getProperty(EXPIRATION_CACHE) call.

            Returns:
                the currently set expiration time in seconds, or 0 if no expiration time is set.

        setExpirationTime

        void setExpirationTime(int time)

            Sets a new expiration time for the current response in seconds.

            If the expiration value is set to 0, caching is disabled for this portlet; if the value is set to -1, the cache does not expire.

            This call is equivalent to calling setProperty(EXPIRATION_CACHE).

            Parameters:
                time - expiration time in seconds
        -------------------------

        Corrected:
        -------------------------
        getExpirationTime

        int getExpirationTime()

            Get the currently set expiration time. If no expiration time has been explicitly set on this response,
            the default defined in the portlet deployment descriptor with the expiration-cache tag is returned; If
            no default value is provided, 0 is assumed.

            This call returns the same value as the getProperty(EXPIRATION_CACHE) call.

            Returns:
                the currently set expiration time in seconds; 0 indicates caching is disabled for this portlet;
                -1 indicates the cache does not expire.

        setExpirationTime

        (unchanged)
        -------------------------
        In the Javadoc for the CacheControl class, the following is stated for getExpirationTime() and setExpirationTime().
        Taken together, it's a bit unclear as to what a return value of 0 from getExpirationTime() actually means - does
        it mean "hasn't been set" or does it mean "disabled"?

        The description for getExpirationTime() should be changed as indicated. The description for setExpirationTime() would remain unchanged.

        {noformat}
        Original:
        -------------------------
        getExpirationTime

        int getExpirationTime()

            Get the currently set expiration time. If no expiration time is set on this response
            the default defined in the portlet deployment descriptor with the expiration-cache
            tag is returned, or 0 if no default is defined.

            This call returns the same value as the getProperty(EXPIRATION_CACHE) call.

            Returns:
                the currently set expiration time in seconds, or 0 if no expiration time is set.

        setExpirationTime

        void setExpirationTime(int time)

            Sets a new expiration time for the current response in seconds.

            If the expiration value is set to 0, caching is disabled for this portlet;
            if the value is set to -1, the cache does not expire.

            This call is equivalent to calling setProperty(EXPIRATION_CACHE).

            Parameters:
                time - expiration time in seconds
        -------------------------

        Corrected:
        -------------------------
        getExpirationTime

        int getExpirationTime()

            Get the currently set expiration time. If no expiration time has been
            explicitly set on this response, the default defined in the portlet
            deployment descriptor with the expiration-cache tag is returned; If
            no default value is provided in the portlet deployment descriptor,
            0 is returned.

            This call returns the same value as the getProperty(EXPIRATION_CACHE) call.

            Returns:
                the currently set expiration time in seconds;
                0 indicates caching is disabled for this portlet;
                -1 indicates the cache does not expire.

        setExpirationTime

        (unchanged)
        -------------------------
        {noformat}
        Hide
        msnicklous added a comment -

        Updated javadoc comments.

        Show
        msnicklous added a comment - Updated javadoc comments.
        msnicklous made changes -
        Status Open [ 1 ] Resolved [ 5 ]
        Resolution Fixed [ 1 ]
        Hide
        msnicklous added a comment -

        Fix discussed on 20130723 and was accepted.

        Show
        msnicklous added a comment - Fix discussed on 20130723 and was accepted.
        msnicklous made changes -
        Status Resolved [ 5 ] Closed [ 6 ]

          People

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

            Dates

            • Created:
              Updated:
              Resolved: