RFR [9] 8039527: Broken links in ConcurrentMap javadoc

[Chris Hegarty]

On 10 Apr 2014, at 11:03, David Holmes <david.holmes at oracle.com> wrote:

> Looks good to me too Chris.

Thanks for looking at this David. Unfortunately I pushed before receiving this mail, so you are not listed as a reviewer on the changeset,

> But I can't help wonder if there is a design flaw in javadoc here, as this means you should never use relative links in any doc element that might be inherited. Which almost reduces to never use relative links. :(

Right. This could be considered an issue with javadoc. It is difficult to say if relative hrefs should be resolved against the subtypes package hierarchy. At the very least a bug against the javadoc tool should be filed so that we can get final clarification on expected behaviour. I will do this.

-Chris.


> 
> David
> 
> On 10/04/2014 12:07 AM, Chris Hegarty wrote:
>> 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.