JDK-8309239 : SequencedMap view method specification and implementation adjustments
  • Type: CSR
  • Component: core-libs
  • Sub-Component: java.util:collections
  • Priority: P3
  • Status: Closed
  • Resolution: Approved
  • Fix Versions: 21
  • Submitted: 2023-05-31
  • Updated: 2023-06-01
  • Resolved: 2023-06-01
Related Reports
CSR :  
Description
Summary
-------

Additional assertions are required in the implementation specifications of the sequenced view default methods of the SequencedMap interface.

Problem
-------

The current implementation specifications of these default methods disagreed with their actual implementations. In addition, the implementations didn't have quite the right behavior in certain cases.

Solution
--------

Adjust the implementations and then rewrite the implementation specifications to match the actual implementations. See diffs below for the `@implSpec` sections of the `sequencedKeySet()`, `sequencedValues()`, and `sequencedEntrySet()` methods of the `SequencedMap` interface.

Specification
-------------

    sequencedKeySet():

          * @implSpec
    -     * The implementation in this interface returns a {@code SequencedSet}
    -     * implementation that delegates all operations either to this map or to this map's
    -     * {@link #keySet}, except for its {@link SequencedSet#reversed reversed} method,
    -     * which instead returns the result of calling {@code sequencedKeySet} on this map's
    -     * reverse-ordered view.
    +     * The implementation in this interface returns a {@code SequencedSet} instance
    +     * that behaves as follows. Its {@link SequencedSet#add add} and {@link
    +     * SequencedSet#addAll addAll} methods throw {@link UnsupportedOperationException}.
    +     * Its {@link SequencedSet#reversed reversed} method returns the {@link
    +     * #sequencedKeySet sequencedKeySet} view of the {@link #reversed reversed} view of
    +     * this map. Each of its other methods calls the corresponding method of the {@link
    +     * #keySet keySet} view of this map.

    sequencedValues():

          * @implSpec
    -     * The implementation in this interface returns a {@code SequencedCollection}
    -     * implementation that delegates all operations either to this map or to this map's
    -     * {@link #values} collection, except for its {@link SequencedCollection#reversed reversed}
    -     * method, which instead returns the result of calling {@code sequencedValues} on this map's
    -     * reverse-ordered view.
    +     * The implementation in this interface returns a {@code SequencedCollection} instance
    +     * that behaves as follows. Its {@link SequencedCollection#add add} and {@link
    +     * SequencedCollection#addAll addAll} methods throw {@link UnsupportedOperationException}.
    +     * Its {@link SequencedCollection#reversed reversed} method returns the {@link
    +     * #sequencedValues sequencedValues} view of the {@link #reversed reversed} view of
    +     * this map. Its {@link Object#equals equals} and {@link Object#hashCode hashCode} methods
    +     * are inherited from {@link Object}. Each of its other methods calls the corresponding
    +     * method of the {@link #values values} view of this map.

    sequencedEntrySet():

          * @implSpec
    -     * The implementation in this interface returns a {@code SequencedSet}
    -     * implementation that delegates all operations either to this map or to this map's
    -     * {@link #entrySet}, except for its {@link SequencedSet#reversed reversed} method,
    -     * which instead returns the result of calling {@code sequencedEntrySet} on this map's
    -     * reverse-ordered view.
    +     * The implementation in this interface returns a {@code SequencedSet} instance
    +     * that behaves as follows. Its {@link SequencedSet#add add} and {@link
    +     * SequencedSet#addAll addAll} methods throw {@link UnsupportedOperationException}.
    +     * Its {@link SequencedSet#reversed reversed} method returns the {@link
    +     * #sequencedEntrySet sequencedEntrySet} view of the {@link #reversed reversed} view of
    +     * this map. Each of its other methods calls the corresponding method of the {@link
    +     * #entrySet entrySet} view of this map.


Comments
Moving to Approved.
01-06-2023