search

jsr107 / jsr107spec

JSR107 Cache Specification
Apache License 2.0
413 stars 164 forks source link

CacheManager.getCacheNames() javadoc is inconsistent with Iterator.remove() #334

Closed jfialli closed 8 years ago

jfialli commented 8 years ago

Specification inconsistency with existing Iterator.remove() javadoc:

The javadoc for java.util.Iterator.remove() is documented to throw UnsupportedOperationException when it is not supported by an implementation. http://docs.oracle.com/javase/7/docs/api/java/util/Iterator.html#remove%28%29

Page 24 of the specification and CacheManager.getCacheNames() method javadoc explicitly contradicts the above.

Obtains an Iterable over the names of Caches managed by the CacheManager.

java.util.Iterators returned by the Iterable are immutable. Any modification of the java.util.Iterator, including remove, will raise an IllegalStateException.

The TCK test org.jsr107.tck.CacheManagerTest.getCaches_MutateReturn handles an expected UnsupportedOperationException.

The RI returns the cache names as an iterator of an unmodifiable collection.

Proposed resolution:

Fix CacheManager.getCachNames() javadoc and specification to not contradict the javadoc for java.util.Iterator.remove(). Simply stating that the returned iterated behaves as an iterator of an unmodifiable collection is sufficient.

Make CacheManagerTest.getCaches_MutateReturn invalid TCK test until spec is rev'ed with this fix. (Filing a separate TCK issue to record this proposal)

cruftex commented 8 years ago

+1 for changing the Spec.

gregrluck commented 8 years ago

So to be absolutely clear, what is being requested is to change the JavaDoc and spec to say:

"Obtains an Iterable over the names of Caches managed by the CacheManager. java.util.Iterators returned by the Iterable are immutable."

We drop the last sentence which means that UnsupportedOperationException must be thrown. UmodifiableCollection does this.