RFR: 8345065: Cleanup DomainCombiner, SubjectDomainCombiner, Subject, and PrivilegedAction specifications

[Sean Mullan]

On Tue, 3 Dec 2024 13:43:25 GMT, Alan Bateman <alanb at openjdk.org> wrote:

>> A few additional changes should be made to the API specs for these classes .  These changes are documenting behavior of other APIs that has already been approved as part of JEP 486, so I don't think a CSR is necessary, but opinions on that are welcome.
>> 
>> The `DomainCombiner` and `SubjectDomainCombiner` classes contain wording about "inherited" and"privileged" `ProtectionDomain`s which is no longer  implemented, and so has been removed. The `PrivilegedAction` classes also contained wording about "privileged" computations which is no longer accurate. I also added an API note to these classes, similar to the ones in the `Permission` subclasses. Finally, I removed a couple of instances of "privileged work" from the `Subject` class which no longer applies.
>
> src/java.base/share/classes/javax/security/auth/Subject.java line 456:
> 
>> 454: 
>> 455:     /**
>> 456:      * Perform work as a particular {@code Subject}.
> 
> The new callAs is specified as "Executes a Callable with subject as the current subject".  ScopedValue uses "Runs an operation with each scoped value in this mapping bound to its value in the current thread" and "Calls a value-returning operation with each scoped value in this mapping bound to its value in the current thread".
> 
> Looking at the doAs and doAsPrivileged methods makes me wonder if "Perform work" should be replaced rather than just dropping the word "privileged". That is, maybe these methods should are re-worded to specify that they run an action rather than "perform work". I realise this is more than what this PR is about, I'm just observing that "Perform work" is strange to see in the API docs.

Well the "perform work" words have been there for a long time. Perhaps "Performs the specified action as a particular subject" which would be more consistent with `AccessController.doPrivileged`. But, I'm also wary of making too many changes.

-------------

PR Review Comment: https://git.openjdk.org/jdk/pull/22500#discussion_r1867783030