Deprecation beyond the level of types

Stephan Herrmann stephan.herrmann at
Sun Apr 1 11:31:50 UTC 2018

I'm looking at how deprecation affects elements larger than types,
and it seems to me that deprecation is much weaker than it could be.

Packages: JLS & javadoc agree that @Deprecated applied to a package
has no effect. Given that @Target explicitly includes PACKAGE this
looks inconsistent to me. A user adding @Deprecated to a package would
certainly expect *some* effect, no?
JLS argues about the same programmer developing the package and
managing its export from then enclosing module. I fail to see how this
justifies the decision to let deprecation of packages go without warning.
If a library developer deprecates an exported package, shouldn't this
signal to consumers of the library, that they should migrate away from
using types within that package? Currently it doesn't, because consumers
will see no effect of that deprecation.

Modules: I could find no reference in JLS specifying any relation between
modules and deprecation. In the javadoc of @Deprecated, however, I find
some additions (apparently not provided/reviewed via jigsaw), notably:
  "A module being deprecated does not cause warnings to be issued for
   uses of types within the module."
I assume "within the module" binds to "types" not "uses", right?
(nitpick: "within the module" is not a specified term, "associated with" is).
For a named module, this makes sense, since "requires" will already raise
a warning for the deprecated module, and hence flagging each use of a type
from that module adds little value.
For unnamed modules, however, this seems to completely bypass any module-
level deprecation. There is no "requires" that could be flagged, and use
of types from the deprecated modules isn't flagged either.

Ergo: most today's consumers of libraries that deprecate either a module
or a package will not be informed about this deprecation by compilers.

If the rules of JEP 261 define the set of default root modules in a way
that ensures that no deprecated modules are in the module graph, then I
could imagine as the very minimum that any command line option that pulls
in a deprecated module (--add-modules, --modulepath, maybe more), will
trigger a warning. The only real problem with that approach is that there
is no place where these warnings could be individually suppressed (unless
new options were introduced like --add-deprecated-modules ...).

I see two consequences from the above:
There's little to no incentive to use @Deprecated at any level greater than
types, because it is not reliably communicated to users. We keep thinking
in terms of types, not modules (not even packages).
Second, developers of unnamed modules will see fewer deprecation warnings.
Hence, migrating from unnamed to named has an additional burden of having
to deal with warnings that could have been dealt with before, but simply
weren't visible.

Are there any plans to improve in this area?

PS: I also checked if JEP 277 has a say on these issues, but the JEP page
doens't give any hints in this direction. As always please let us know if
there is more recent information regarding any of the closed JEPs.

More information about the jigsaw-dev mailing list