Summary
-------

Deprecate the Java Management Extension (JMX) Subject Delegation feature, which means the method `javax.management.remote.JMXConnector.getMBeanServerConnection(javax.security.auth.Subject)`, for removal in a future release.

Problem
-------

Subject Delegation requires a security policy file to grant javax.management.remote.SubjectDelegationPermission, and the implementation relies on deprecated methods such as `java.security.AccessController::checkPermission` and `java.security.AccessControlContext::checkPermission.`  These are deprecated for removal as part of JEP 411: the Security Manager is already considered a legacy feature and deprecated for removal.

These deprecated methods will cease to be usable once the Security Manager is further degraded and eventually removed.  If methods such as `AccessController::checkPermission` are degraded before this feature is removed (for example to throw an AccessControlException on any usage), then the SubjectDelegation feature will be unusable before it is removed.

There is no known usage of this method based on a Maven corpus search.

The interface `javax.management.remote.rmi.RMIConnection` contains methods which accept a Subject, to implement Subject Delegation. These methods are commonly called with a null Subject, for the previously authenticated principal to be used. User code does not normally interact with these methods, but when this feature is removed their existing use of SecurityException should be updated.


Solution
--------

We will terminally deprecate the feature. 

When this feature is removed in the future, if a client connects to a new server that does not support this feature and request to perform an operation in the remote server with the delegation subject, `SecurityException` will be thrown per the specification of `javax.management.remote.rmi.RMIConnection` methods because the delegation subject has no permission to perform the operations.

```
SecurityException - if the client, or the delegated Subject if any, does not have permission to perform this operation.
```

The `@throws SecurityException` javadoc can be clarified when this feature is removed and the exception message at that time will make clear that the feature is not supported.

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

We will terminally deprecate, by annotating with @Deprecated(since="21", forRemoval=true), the method:

 - `javax.management.remote.JMXConnector.getMBeanServerConnection(Subject delegationSubject)`


The commonly used no-argument getMBeanServerConnection() method is not affected.

The API documentation will include the deprecation text:

This method supported the legacy Subject Delegation feature, and is only useful in conjunction with other APIs which are deprecated and subject to removal in a future release. Consequently, this method is also deprecated and subject to removal. There is no replacement.

Methods in the interface `javax.management.remote.rmi.RMIConnection` that take a `delegationSubject` parameter are not affected, but will throw a `SecurityException` if a non-null delegation subject is provided once the subject delegation feature is removed.