Issue Details (XML | Word | Printable)

Key: PORTLETSPEC3-3
Type: Improvement Improvement
Status: Closed Closed
Resolution: Fixed
Priority: Minor Minor
Assignee: Unassigned
Reporter: msnicklous
Votes: 0
Watchers: 0
Operations

If you were logged in you would be able to see more operations.
portletspec3

Errata: Clarification in Javadoc for CacheControl.getExpirationTime()

Created: 30/Apr/13 02:16 PM   Updated: 26/Jul/13 09:39 AM   Resolved: 17/Jul/13 02:06 PM
Component/s: JSR 286 Portlet Specification Errata
Affects Version/s: None
Fix Version/s: None

Time Tracking:
Not Specified

Tags: JSR286 portlet
Participants: mfreedma, msnicklous and Neil Griffin


 Description  « Hide

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


mfreedma added a comment - 08/May/13 06:08 PM

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.


Neil Griffin added a comment - 11/May/13 07:17 PM

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


msnicklous added a comment - 13/May/13 07:25 AM

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


msnicklous added a comment - 09/Jul/13 01:43 PM

updated formatting; incorporated suggested text change.


msnicklous added a comment - 17/Jul/13 02:06 PM

Updated javadoc comments.


msnicklous added a comment - 26/Jul/13 09:39 AM

Fix discussed on 20130723 and was accepted.