RFR [9] 8039527: Broken links in ConcurrentMap javadoc

[Chris Hegarty]

java.util.concurrent.ConcurrentMap contains several broken links to 
Collection.html#optional-restrictions. See
 
http://docs.oracle.com/javase/8/docs/api/java/util/concurrent/ConcurrentMap.html

The issue is caused by the use of '{@inheritDoc}' in many '@throws' 
definitions. ConcurrentMap's superType Map, is in the java.util package. 
Map has documentation references to Collection.html, which is in the 
same package as Map, java.util, but since ConcurrentMap is not in 
java.util it needs different relative links, or better still links 
relative to the docRoot.

Trivial diffs inline:

diff --git a/src/share/classes/java/util/Map.java 
b/src/share/classes/java/util/Map.java
--- a/src/share/classes/java/util/Map.java
+++ b/src/share/classes/java/util/Map.java
@@ -157,10 +157,10 @@
       *         key
       * @throws ClassCastException if the key is of an inappropriate 
type for
       *         this map
-     * (<a href="Collection.html#optional-restrictions">optional</a>)
+     * (<a 
href="{@docRoot}/java/util/Collection.html#optional-restrictions">optional</a>)
       * @throws NullPointerException if the specified key is null and 
this map
       *         does not permit null keys
-     * (<a href="Collection.html#optional-restrictions">optional</a>)
+     * (<a 
href="{@docRoot}/java/util/Collection.html#optional-restrictions">optional</a>)
       */
      boolean containsKey(Object key);

@@ -177,10 +177,10 @@
       *         specified value
       * @throws ClassCastException if the value is of an inappropriate 
type for
       *         this map
-     * (<a href="Collection.html#optional-restrictions">optional</a>)
+     * (<a 
href="{@docRoot}/java/util/Collection.html#optional-restrictions">optional</a>)
       * @throws NullPointerException if the specified value is null and 
this
       *         map does not permit null values
-     * (<a href="Collection.html#optional-restrictions">optional</a>)
+     * (<a 
href="{@docRoot}/java/util/Collection.html#optional-restrictions">optional</a>)
       */
      boolean containsValue(Object value);

@@ -204,10 +204,10 @@
       *         {@code null} if this map contains no mapping for the key
       * @throws ClassCastException if the key is of an inappropriate 
type for
       *         this map
-     * (<a href="Collection.html#optional-restrictions">optional</a>)
+     * (<a 
href="{@docRoot}/java/util/Collection.html#optional-restrictions">optional</a>)
       * @throws NullPointerException if the specified key is null and 
this map
       *         does not permit null keys
-     * (<a href="Collection.html#optional-restrictions">optional</a>)
+     * (<a 
href="{@docRoot}/java/util/Collection.html#optional-restrictions">optional</a>)
       */
      V get(Object key);

@@ -264,10 +264,10 @@
       *         is not supported by this map
       * @throws ClassCastException if the key is of an inappropriate 
type for
       *         this map
-     * (<a href="Collection.html#optional-restrictions">optional</a>)
+     * (<a 
href="{@docRoot}/java/util/Collection.html#optional-restrictions">optional</a>)
       * @throws NullPointerException if the specified key is null and this
       *         map does not permit null keys
-     * (<a href="Collection.html#optional-restrictions">optional</a>)
+     * (<a 
href="{@docRoot}/java/util/Collection.html#optional-restrictions">optional</a>)
       */
      V remove(Object key);

@@ -577,10 +577,10 @@
       * {@code defaultValue} if this map contains no mapping for the key
       * @throws ClassCastException if the key is of an inappropriate 
type for
       * this map
-     * (<a href="Collection.html#optional-restrictions">optional</a>)
+     * (<a 
href="{@docRoot}/java/util/Collection.html#optional-restrictions">optional</a>)
       * @throws NullPointerException if the specified key is null and 
this map
       * does not permit null keys
-     * (<a href="Collection.html#optional-restrictions">optional</a>)
+     * (<a 
href="{@docRoot}/java/util/Collection.html#optional-restrictions">optional</a>)
       * @since 1.8
       */
      default V getOrDefault(Object key, V defaultValue) {
@@ -659,13 +659,13 @@
       * values
       * @throws ClassCastException if a replacement value is of an 
inappropriate
       *         type for this map
-     *         (<a 
href="Collection.html#optional-restrictions">optional</a>)
+     *         (<a 
href="{@docRoot}/java/util/Collection.html#optional-restrictions">optional</a>)
       * @throws NullPointerException if function or a replacement value 
is null,
       *         and this map does not permit null keys or values
-     *         (<a 
href="Collection.html#optional-restrictions">optional</a>)
+     *         (<a 
href="{@docRoot}/java/util/Collection.html#optional-restrictions">optional</a>)
       * @throws IllegalArgumentException if some property of a 
replacement value
       *         prevents it from being stored in this map
-     *         (<a 
href="Collection.html#optional-restrictions">optional</a>)
+     *         (<a 
href="{@docRoot}/java/util/Collection.html#optional-restrictions">optional</a>)
       * @throws ConcurrentModificationException if an entry is found to be
       * removed during iteration
       * @since 1.8
@@ -726,16 +726,16 @@
       *         if the implementation supports null values.)
       * @throws UnsupportedOperationException if the {@code put} operation
       *         is not supported by this map
-     *         (<a 
href="Collection.html#optional-restrictions">optional</a>)
+     *         (<a 
href="{@docRoot}/java/util/Collection.html#optional-restrictions">optional</a>)
       * @throws ClassCastException if the key or value is of an 
inappropriate
       *         type for this map
-     *         (<a 
href="Collection.html#optional-restrictions">optional</a>)
+     *         (<a 
href="{@docRoot}/java/util/Collection.html#optional-restrictions">optional</a>)
       * @throws NullPointerException if the specified key or value is null,
       *         and this map does not permit null keys or values
-     *         (<a 
href="Collection.html#optional-restrictions">optional</a>)
+     *         (<a 
href="{@docRoot}/java/util/Collection.html#optional-restrictions">optional</a>)
       * @throws IllegalArgumentException if some property of the 
specified key
       *         or value prevents it from being stored in this map
-     *         (<a 
href="Collection.html#optional-restrictions">optional</a>)
+     *         (<a 
href="{@docRoot}/java/util/Collection.html#optional-restrictions">optional</a>)
       * @since 1.8
       */
      default V putIfAbsent(K key, V value) {
@@ -772,13 +772,13 @@
       * @return {@code true} if the value was removed
       * @throws UnsupportedOperationException if the {@code remove} 
operation
       *         is not supported by this map
-     *         (<a 
href="Collection.html#optional-restrictions">optional</a>)
+     *         (<a 
href="{@docRoot}/java/util/Collection.html#optional-restrictions">optional</a>)
       * @throws ClassCastException if the key or value is of an 
inappropriate
       *         type for this map
-     *         (<a 
href="Collection.html#optional-restrictions">optional</a>)
+     *         (<a 
href="{@docRoot}/java/util/Collection.html#optional-restrictions">optional</a>)
       * @throws NullPointerException if the specified key or value is null,
       *         and this map does not permit null keys or values
-     *         (<a 
href="Collection.html#optional-restrictions">optional</a>)
+     *         (<a 
href="{@docRoot}/java/util/Collection.html#optional-restrictions">optional</a>)
       * @since 1.8
       */
      default boolean remove(Object key, Object value) {
@@ -821,14 +821,14 @@
       * @return {@code true} if the value was replaced
       * @throws UnsupportedOperationException if the {@code put} operation
       *         is not supported by this map
-     *         (<a 
href="Collection.html#optional-restrictions">optional</a>)
+     *         (<a 
href="{@docRoot}/java/util/Collection.html#optional-restrictions">optional</a>)
       * @throws ClassCastException if the class of a specified key or value
       *         prevents it from being stored in this map
       * @throws NullPointerException if a specified key or newValue is 
null,
       *         and this map does not permit null keys or values
       * @throws NullPointerException if oldValue is null and this map 
does not
       *         permit null values
-     *         (<a 
href="Collection.html#optional-restrictions">optional</a>)
+     *         (<a 
href="{@docRoot}/java/util/Collection.html#optional-restrictions">optional</a>)
       * @throws IllegalArgumentException if some property of a 
specified key
       *         or value prevents it from being stored in this map
       * @since 1.8
@@ -871,10 +871,10 @@
       *         if the implementation supports null values.)
       * @throws UnsupportedOperationException if the {@code put} operation
       *         is not supported by this map
-     *         (<a 
href="Collection.html#optional-restrictions">optional</a>)
+     *         (<a 
href="{@docRoot}/java/util/Collection.html#optional-restrictions">optional</a>)
       * @throws ClassCastException if the class of the specified key or 
value
       *         prevents it from being stored in this map
-     *         (<a 
href="Collection.html#optional-restrictions">optional</a>)
+     *         (<a 
href="{@docRoot}/java/util/Collection.html#optional-restrictions">optional</a>)
       * @throws NullPointerException if the specified key or value is null,
       *         and this map does not permit null keys or values
       * @throws IllegalArgumentException if some property of the 
specified key
@@ -942,10 +942,10 @@
       *         is null
       * @throws UnsupportedOperationException if the {@code put} operation
       *         is not supported by this map
-     *         (<a 
href="Collection.html#optional-restrictions">optional</a>)
+     *         (<a 
href="{@docRoot}/java/util/Collection.html#optional-restrictions">optional</a>)
       * @throws ClassCastException if the class of the specified key or 
value
       *         prevents it from being stored in this map
-     *         (<a 
href="Collection.html#optional-restrictions">optional</a>)
+     *         (<a 
href="{@docRoot}/java/util/Collection.html#optional-restrictions">optional</a>)
       * @since 1.8
       */
      default V computeIfAbsent(K key,
@@ -1003,10 +1003,10 @@
       *         remappingFunction is null
       * @throws UnsupportedOperationException if the {@code put} operation
       *         is not supported by this map
-     *         (<a 
href="Collection.html#optional-restrictions">optional</a>)
+     *         (<a 
href="{@docRoot}/java/util/Collection.html#optional-restrictions">optional</a>)
       * @throws ClassCastException if the class of the specified key or 
value
       *         prevents it from being stored in this map
-     *         (<a 
href="Collection.html#optional-restrictions">optional</a>)
+     *         (<a 
href="{@docRoot}/java/util/Collection.html#optional-restrictions">optional</a>)
       * @since 1.8
       */
      default V computeIfPresent(K key,
@@ -1079,10 +1079,10 @@
       *         remappingFunction is null
       * @throws UnsupportedOperationException if the {@code put} operation
       *         is not supported by this map
-     *         (<a 
href="Collection.html#optional-restrictions">optional</a>)
+     *         (<a 
href="{@docRoot}/java/util/Collection.html#optional-restrictions">optional</a>)
       * @throws ClassCastException if the class of the specified key or 
value
       *         prevents it from being stored in this map
-     *         (<a 
href="Collection.html#optional-restrictions">optional</a>)
+     *         (<a 
href="{@docRoot}/java/util/Collection.html#optional-restrictions">optional</a>)
       * @since 1.8
       */
      default V compute(K key,
@@ -1157,10 +1157,10 @@
       *         value is associated with the key
       * @throws UnsupportedOperationException if the {@code put} operation
       *         is not supported by this map
-     *         (<a 
href="Collection.html#optional-restrictions">optional</a>)
+     *         (<a 
href="{@docRoot}/java/util/Collection.html#optional-restrictions">optional</a>)
       * @throws ClassCastException if the class of the specified key or 
value
       *         prevents it from being stored in this map
-     *         (<a 
href="Collection.html#optional-restrictions">optional</a>)
+     *         (<a 
href="{@docRoot}/java/util/Collection.html#optional-restrictions">optional</a>)
       * @throws NullPointerException if the specified key is null and 
this map
       *         does not support null keys or the value or 
remappingFunction is
       *         null

-Chris.