Summary

java.lang.ModuleLayer::parents needs to specify that it returns an unmodifiable list of module layers.

Problem

This is an oversight in the original specification and implementation. Module layers are immutable, the list returned by the parents() method should be an unmodifiable list. The equivalent parents() method in java.lang.module.Configuration correctly specifies that the list is unmodifiable. The set of modules returned by ModuleLayer::modules and Configuration::modules also specify that the sets are unmodifable.

Solution

Change the specification of ModuleLayer::parents to specify that the list is unmodifiable.

Update the implementation to return an unmodifiable list. The compatibility impact of changing the implementation is minimal, nothing could rely on being able to modify the list.

Specification

Change the specification for ModuleLayer::parents to specify that it returns an unmodifiable list:

     /**
-     * Returns the list of this layer's parents unless this is the
-     * {@linkplain #empty empty layer}, which has no parents and so an
+     * Returns an unmodifiable list of this layer's parents, in search
+     * order. If this is the {@linkplain #empty() empty layer} then an
      * empty list is returned.
      *
-     * @return The list of this layer's parents
+     * @return A possibly-empty unmodifiable list of this layer's parents
      */

Adjust the specification for ModuleLayer::modules to make it clearer that it returns an unmodifiable set (this does not introduce any testable assertions because the @return also specifies that it returns an unmodifiable set.

     /**
-     * Returns the set of the modules in this layer.
+     * Returns an unmodifiable set of the modules in this layer.
      *
      * @return A possibly-empty unmodifiable set of the modules in this layer
      */