Summary

Change com.sun.jdi.ObjectReference.setValue to specify that it cannot be used to change final instance fields, and align it with long standing implementation behavior.

Problem

ObjectReference.setValue spec says:

Sets the value of a given instance or static field in this object. The Field must be
valid for this ObjectReference; that is, it must be from the mirrored object's class
or a superclass of that class. If static, the field must not be final.

The JDK's JDI implementation has never allowed a final field (static or instance) be changed. The current behavior, and spec vs. implementation difference, goes back to 1999.

Solution

Changes the description ObjectReference.setValue to specify that the method cannot be used to change final fields.

Change the description of the IllegalArgumentException to include the condition that the field is final.

Specification

old:

/**
 * Sets the value of a given instance or static field in this object.
 * The {@link Field} must be valid for this ObjectReference; that is,
 * it must be from the mirrored object's class or a superclass of that class.
 * If static, the field must not be final.
 * <p>
 ...
 * @throws java.lang.IllegalArgumentException if the field is not valid for
 * this object's class.
 ...
 */
void setValue(Field field, Value value)

new:

/**
 * Sets the value of a given instance or static field in this object.
 * The {@link Field} must be valid for this ObjectReference; that is,
 * it must be from the mirrored object's class or a superclass of that class.
 * The field must not be final.
 * <p>
 ...
 * @throws java.lang.IllegalArgumentException if the field is not valid for
 * this object's class or the field is final.
 ...
 */
void setValue(Field field, Value value)