I should have mentioned that the API flaws breaking with Bloch's advice can be really nasty. I bundled up a bunch of items under that, which might mundane if you don't know of them. Some of the wonderful design choices are,
- Cache.iterator() may return a null entry, despite null key or value is disallowed. This occurs when the cursor points to an entry that no longer exists - hasNext() was true, but the entry disappeared due to removal/eviction/expiration. This is a performance optimization to avoid underlying I/O that leaks to users and violates their assumptions.
- Cache.putAll(map) first invokes CacheWriter.writeAll(list<entry>) prior to storing them. The writer uses an in/out parameter so that if an exception is thrown, the user must remove the successfully written entries first. Then cache must store those successfully written entries before propagating the exception to the caller.
- An amusing bug was that their custom future could not be consumed by multiple threads. It used notify(), not notifyAll(), so only one waiter would wake up. The concerning part was that this existed for a few years due to lack interest in releasing a new version.
- Cache.iterator() may return a null entry, despite null key or value is disallowed. This occurs when the cursor points to an entry that no longer exists - hasNext() was true, but the entry disappeared due to removal/eviction/expiration. This is a performance optimization to avoid underlying I/O that leaks to users and violates their assumptions.
- Cache.putAll(map) first invokes CacheWriter.writeAll(list<entry>) prior to storing them. The writer uses an in/out parameter so that if an exception is thrown, the user must remove the successfully written entries first. Then cache must store those successfully written entries before propagating the exception to the caller.
- An amusing bug was that their custom future could not be consumed by multiple threads. It used notify(), not notifyAll(), so only one waiter would wake up. The concerning part was that this existed for a few years due to lack interest in releasing a new version.