JDK-8350135 : Support lint control of sunapi diagnostics
  • Type: CSR
  • Component: tools
  • Sub-Component: javac
  • Priority: P4
  • Status: Draft
  • Resolution: Unresolved
  • Submitted: 2025-02-14
  • Updated: 2025-02-14
Related Reports
CSR :  
Description
Summary
-------

Add a new lint category `proprietary` that controls the mandatory warning "Foo is internal proprietary API and may be removed in a future release".

Problem
-------

There is currently no way to suppress this warning. This puts awkward constraints on the build process of any affected project.

For example, building with `-Werror` is not possible if the project uses e.g. `sun.misc.Unsafe`.

Solution
--------

Put this warning under the control of the Lint mechanism, so it can be controlled via the `-Xlint` flag and `@SuppressWarnings`.

Note that this warning is currently a mandatory warning, so we will preserve that behavior. However, the warning will be newly suppressible, so that means we will also do the normal mandatory warning aggregation logic, in which we emit a "recompile" note, refer to additional files as needed, etc.

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

The usual mandatory warning behavior will apply, for example:
```
$ cat Proprietary.java 
class Proprietary {
    sun.misc.Unsafe x;
}
$ javac -d classes Proprietary.java 
Proprietary.java:2: warning: [proprietary] Unsafe is internal proprietary API and may be removed in a future release
    sun.misc.Unsafe x;
            ^
1 warning
$ javac -d classes -Xlint:-proprietary Proprietary.java 
Note: Proprietary.java uses an internal proprietary API that may be removed in a future release
Note: Recompile with -Xlint:proprietary for details.
$ javac -d classes -Xlint:-proprietary Proprietary.java Proprietary2.java
Note: Some input files use an internal proprietary API that may be removed in a future release
Note: Recompile with -Xlint:proprietary for details.
```

The new lint category will be added to the `--help-lint` output:

```
--- x0	2025-02-14 15:18:27.887776902 -0600
+++ -	2025-02-14 15:18:40.186611000 -0600
@@ -23,6 +23,7 @@
     overrides            Warn about issues regarding method overrides.
     path                 Warn about invalid path elements on the command line.
     processing           Warn about issues regarding annotation processing.
+    proprietary          Warn about use of internal proprietary APIs.
     rawtypes             Warn about use of raw types.
     removal              Warn about use of API that has been marked for removal.
     requires-automatic   Warn about use of automatic modules in the requires clauses.
```


Comments
Hi Liam, I have not delved into the history, though I was wondering the same thing myself. My best guess is that there was a "cleanup" that occurred in which some undocumented options were removed (i.e., JDK-8148808). In theory this was a perfectly valid step: undocumented flags and other hacks that the OpenJDK team members themselves are not using anymore are ripe for removal. But that particular flag `-XDenableSunApiLintControl` was also a useful feature for outsiders and it didn't have any replacement. So apparently people then switched to using `-XDignore.symbol.file` instead, which of course only deferred the problem with the "missing feature" that this change is attempting to finally address. There are still a few other random warnings that are not under "lint control" out there; in an ideal world they all would be.
14-02-2025

This all sounds good to me, thanks Archie for picking this up. Have you been able to find out any of the history behind -XDenableSunApiLintControl and JDK-8148808? I was curious if there'd been a decision not to do this at some point, or what the discussion was behind adding -XDenableSunApiLintControl in the first place and later removing it.
14-02-2025