Caffeine: Caffeine spec time duration format

[asarkar]

1. I couldn't find the format for setting expireAfterAccess in the Wiki. I initially used P7D, which failed, and the stacktrace led me to CaffeineSpec. parseTimeUnit. Ideally, not every new user would have to go through the source code, and it'd be documented under Eviction.
2. ISO-8601 datetime format is almost ubiquitous in modern Java code, especially if using Spring (hence my initial attempt with P7D). It'd be nice to have support for this in Caffeine.

[ben-manes]

The format is documented and matches Guava's CacheSpec,
https://github.com/ben-manes/caffeine/blob/3b1921cdecfbc48911e614ca6542265c38da8a76/caffeine/src/main/java/com/github/benmanes/caffeine/cache/CaffeineSpec.java#L52-L54

We don't have a wiki page on the specification format. Its for convenience but a lot of users will prefer their own configuration file format, so perhaps Spring is the largest adopter of it. The ability to parse ISO-8601 would be fine, but it's also not very readable so I'd be surprised if its used very frequently in config files? HOCON for example has a duration format similar to ours.

[asarkar]

@ben-manes I saw the source code comment, but I was hoping to be able to find it in the Wiki, easily, without going into source code.

Regarding ISO-8601, I agree it's not very readable, but it doesn't need to be; it's a widely used spec, so people can find examples/help more easily than they would with Guava/Caffeine proprietary spec. I had googled Caffeine time duration spec, and got nothing useful. On the other hand, ISO-8601 java parsing examples brings up a slew of practical references.

[ben-manes]

Sure, we can add a new wiki page and alternative time syntax support to the parser.

[asarkar]

I tried to make a PR, but couldn’t find a way to run a single test in IntelliJ and gave up. I’ve not worked with TestNG before, but assumed that I could just right click on a test class/method and run it. No such option was available in the context menu.

[ben-manes]

No problem, I can take care of it. Supposedly it is built into Idea, but I use Eclipse so not familiar. JUnit5's rewrite is mostly a clone of TestNG syntax (thankfully no more JUnit4 craziness), though slower and much more memory hungry when I tried it recently.

fwiw, in your Caffeine time duration spec search the answer you wanted was the 2nd link. 😄 A nice wiki page and more flexibility makes sense regardless, as currently a hidden feature.

[ben-manes]

@asarkar Please review the new wiki page. It is a little dry and copies the JavaDoc, but I suppose that's appropriate given its a simple configuration format. The next release will offer the ISO-8601 format option.

If that looks good, then maybe @tydhot can translate it for us.

[tydhot]

@ben-manes Of course, I'd love to do it.

[asarkar]

@ben-manes You didn't really give me much time to review the Wiki, since it is merged now, but FWIW, I do have couple of comments:

The string syntax is a series of comma-separated keys or key-value pairs, each corresponding to a builder method. This format does not support configuring builder methods with non-value parameters

This seems contradictory; if only comma-separated keys are allowed, then how come it "does not support configuring builder methods with non-value parameters"?

Durations are represented as either ISO-8601 seconds

Why only seconds? Every suffix available now is also supported by Duration, and you could convert to seconds trivially using toSeconds() * 60 (AFAIK, there's no toSeconds until Java 11).

[ben-manes]

how come it "does not support configuring builder methods with non-value parameters"?

This originates from the Guava JavaDoc, but means that it doesn't support ad hoc code such as a fully-qualified class name. It has to be a value like 100 or no parameter (like recordStats) and not methods like removalListener.

Why only seconds?

I took this from Duration#toString which states,

A string representation of this duration using ISO-8601 seconds based representation, 
such as {@code PT8H6M12.345S}.

But then Duration.parse(Duration.ofNanos(1).toString()) does parse (PT0.000000001S) so I am unsure exactly why they worded it that way?

Suggestions on revised wording would be appreciated.

[ben-manes]

You didn't really give me much time to review the Wiki...

Sorry, the code is merged but the wiki is live (as lives outside of the main git repo via a hidden Github repo). We can edit it as desired and can commit further changes, as nothing is released.

[asarkar]

Duration.parse would parse any ISO-8601 valid string, so I'd suggest something like:

A duration is represented as an ISO-8601 format string; some examples are shown below.

"PT21.345S" -- "21.345 seconds"
"PT11M" -- "11 minutes"
"PT11H" -- "11 hours"
"P3D" -- "3 days"
"P3DT3H4M" -- "3 days, 3 hours and 4 minutes"

For the purposes of cache TTL, all fractional values are rounded, and negative durations throw an exception.

The disclaimer about -ve duration is useful because the spec supports it, but makes no sense for caching. So if now + duration <= now, the value is invalid.

"P-7H3M" -- "-7 hours and +3 minutes"
"-P7H3M" -- "-7 hours and -3 minutes"
"-P-7H+3M" -- "+7 hours and -3 minutes"

[ben-manes]

Thank you. I updated the wiki to include those examples and refine the wording.

---

A duration can be represented by an integer followed by one of "d", "h", "m", or "s", representing days, hours, minutes, or seconds respectively. Alternatively, as of v2.8.7, an ISO-8601 format string may be provided and is parsed by Duration.parse. For the purposes of a cache, all fractional values are rounded and negative durations throw an exception. Some examples of the two formats are below.

| Short | ISO-8601 | Description
|-------|:--------|:------------|
| 50s | PT50S | 50 seconds |
| 11m | PT11M | 11 minutes |
| 6h | PT6H | 6 hours |
| 3d | P3D | 3 days |
| | P3DT3H4M| 3 days, 3 hours and 4 minutes |

[asarkar]

Excellent!

[ben-manes]

I also tweaked non-value to be object in the wiki, but kept the JavaDoc to mirror Guava's for now. Thanks again! 😃

[ben-manes]

and saw your edit, so added a negative case to the table.

[tydhot]

@ben-manes Hi, translation of Specification's wiki page is done. https://github.com/ben-manes/caffeine/wiki/Specification-zh-CN

[ben-manes]

Thanks @tydhot!

[ben-manes]

Released 2.8.7