clarifications on CacheWriter javadoc/specifcation and what is testable constraint for tck

[jfialli]

The following javadoc comments from CacheWriter support testing atomicity between cache mutation operation and write-through invocations of CacheWriter.

• Under Default Consistency, the non-batch writer methods are atomic with respect
• to the corresponding cache operation.

---

• @throws javax.cache.CacheException if the write fails. If thrown the

•                              cache mutation will not occur */

  void write(Cache.Entry<? extends K, ? extends V> entry);

---

• @throws javax.cache.CacheException if one or more of the writes fail. If
• thrown cache mutations will occur for

•                              entries which succeeded. */

  void writeAll(Collection<Cache.Entry<? extends K, ? extends V>> entries);

---

• @throws javax.cache.CacheException if delete fails. If thrown the

•                              cache delete will not occur.*/

  void delete(Object key);

---

• @throws javax.cache.CacheException if one or more deletes fail. If thrown

•                cache deletes will occur for entries which succeeded.

  */

  void deleteAll(Collection<?> keys);

---

Possibly contradicting weaking javadoc comments for constraint tests are following comments in CacheWriter javadoc.

• The semantics of write-through when an Exception is thrown are
• implementation specific.

---

• The behaviour of the caching implementation in the case of partial success is
• undefined.

---

Based on clarification, will determine if tck test to test

1. for non-batch operations, if CacheWriter methods throws CacheException, corresponding cache mutation operation will not have occurred.
2. for batch operations (such as putAll and removeAll) if batch method throws a CacheException, that only CacheWriter operations that succeeded also resulted in corresponding cache mutation.

Yes these look like earlier comments which we left in place after we did define the semantics. I have removed those two weakening in the class JavaDoc.

---

Javadoc corrections:

File: Cache.java Methods: boolean remove(K key); boolean remove(K key, V oldValue);

Replace:

• @throws CacheException if there is a problem doing the put With:
• @throws CacheException if there is a problem doing the remove

Fixed. GL

---

Recommended Javadoc Enhancement:

Not as obvious from the Cache mutation operation javadoc that write-through failures throwing CacheException are one of the problems that can cause a cache mutation operation to fail.

Add an @see CacheWriter#write to Cache methods put, getAndPut, putIfAbsent, overloads of replace. getAndReplace.

Add an @see CacheWriter#delete to Cache method overloads of remove and getAndRemove

Add an @see CacheWriter.writeAll to Cache method putAll.

add an @see CacheWriter.deleteAll to Cache method overloads of deleteAll.

All above fixed. GL

---

Strongly recommended Javadoc enhancement for CacheWriter javadoc for batch methods writeAll and deleteAll.

Parameter entries is an in-out parameter for CacheWriter.writeAll and CacheWriter.deleteAll. The javadoc does not point this out sufficiently in javadoc for parameter entries. It is mentioned in the base javadoc for the method, but the parameter entries should directly state what it values signifies upon entering and when returning from the method call.

There is a whole paragraph in there right now on this point:

• If this operation fails (by throwing an exception) after a partial success,
• the writer must remove any successfully written entries from the entries
• collection so that the caching implementation knows what succeeded and can
• mutate the cache.

What exactly do you propose?

---

JSR 107 Specification and JSR 107 API discrepancy on CacheWriter batch methods. Those methods do not use Iterable, they use Set.

See page 16, bullet starting with "Use of Iterable".

Yes, removed the reference to CacheWriter using Iterable. They use Collection though, not Set.

---

Moved exception issue to new issue #224 so that we can some discussion on it.

[gregrluck]

See inline for corrections in each case. Let me know if anything further needs to be done. Have new #224 on the wrapping of exceptions issue.

[jfialli]

Proposal for @param javadoc for CacheWriter.writeAll and CacheWriter.deleteAll.

For writeAll method param:

@param entries Must be a mutable collection. Upon invocation, it contains the entries to write for write-through. Upon return to the caller, collection entries must only contain entries that were not successfully written. (see partial success above)

For deleteAll method param:

@param keys Must be a mutable collection. Upon invocation, it contains the keys to delete for write-through. Upon return to the caller, collection keys must only contain the keys that were not successfully deleted. (see partial success above)