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

[Alan Bateman]

On Mon, 2 Dec 2024 22:18:33 GMT, Sean Mullan <mullan 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.

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

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