[PORTLETSPEC3-3] Errata: Clarification in Javadoc for CacheControl.getExpirationTime() Created: 30/Apr/13  Updated: 26/Jul/13  Resolved: 17/Jul/13

Status: Closed
Project: portletspec3
Component/s: JSR 286 Portlet Specification Errata
Affects Version/s: None
Fix Version/s: None

Type: Improvement Priority: Minor
Reporter: msnicklous Assignee: Unassigned
Resolution: Fixed Votes: 0
Labels: None
Remaining Estimate: Not Specified
Time Spent: Not Specified
Original Estimate: Not Specified

Tags: JSR286, portlet

 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)
-------------------------


 Comments   
Comment by mfreedma [ 08/May/13 ]

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.

Comment by Neil Griffin [ 11/May/13 ]

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

Comment by msnicklous [ 13/May/13 ]

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

Comment by msnicklous [ 09/Jul/13 ]

updated formatting; incorporated suggested text change.

Comment by msnicklous [ 17/Jul/13 ]

Updated javadoc comments.

Comment by msnicklous [ 26/Jul/13 ]

Fix discussed on 20130723 and was accepted.

Generated at Sun Mar 26 08:37:36 UTC 2017 using JIRA 6.2.3#6260-sha1:63ef1d6dac3f4f4d7db4c1effd405ba38ccdc558.