Proposal: #ModuleAnnotations and #ModuleDeprecation

Wed Jun 29 15:18:17 UTC 2016

Replying to the "observers" list...

>> Annotations on modules will never affect the operation of the module
system itself.

Is that really true? If by "module system" you are excluding layer
interaction, okay, but I do expect annotations to impact how modules are
loaded. At the minimum, annotations may instruct the module system or layer
to do extra logging. Envisioning greater impact, I also could see the use
case where a layer uses annotations, such as identifying the Maven GAV, to
check against the Victims CVE database and fail loading compromised
modules. [1] If I remember correctly, layers do have the chance to
customize the module descriptor -- which includes failing to load it with
an exception, no? If not, please consider a layer's veto power as an RFE.

However, regarding module annotations being invisible, making them
invisible was supposed to prevent providing actionable information. So if
module annotations are runtime visible, expect layers to use them to
customize how modules are loaded.

>> Should it be possible to annotate the individual directives in a module
declaration?

If you do allow this, you should have corresponding mirror elements created
in javax.lang.model so that developers can inspect the element constructs.

[1] https://www.owasp.org/index.php/OWASP_Dependency_Check

Cheers,
Paul

On Wed, Jun 29, 2016 at 7:30 AM, Stephen Colebourne <scolebourne at joda.org>
wrote:

> Like Remi and David, I support the proposal, but feel that annotations
> should be available at runtime. Not doing so would be very surprising
> to end users, and would be an "unpleasant asymmetry in the language".
>
> While I can see the case for annotations within the module-info file
> (Stephane makes a good case), I'm OK with omitting it.
>
> Stephen
>
>
> On 28 June 2016 at 22:19, Mark Reinhold <mark.reinhold at oracle.com> wrote:
> > Issue summaries
> > ---------------
> >
> >   #ModuleAnnotations --- Should it be possible to annotate module
> >   declarations?  As previously discussed this is technically feasible
> >   but it would add significant complexity. [1]
> >
> >   #ModuleDeprecation -- If module declarations cannot be annotated,
> >   should there be some other way to deprecate modules? [2]
> >
> > Proposal
> > --------
> >
> > Allow arbitrary annotations to be placed on module declarations, and
> > revise the `java.lang.Deprecated` annotation so that it can be applied
> > to modules.
> >
> >   - Add a new value, `MODULE`, to `java.lang.annotation.ElementType`,
> >     to denote the top level of a module declaration.
> >
> >   - Extend `javax.lang.model` and `java.lang.reflect` to provide access
> >     to module annotations.  Repeating annotations are supported, subject
> >     to the usual rules for repeatable annotation types.  (This proposal
> >     will not add similar support to `java.lang.module.ModuleDescriptor`;
> >     that would add yet more complexity, and we haven't seen a use case
> >     for it.)
> >
> >   - Annotations on modules will never affect the operation of the module
> >     system itself.
> >
> >   - Revise `java.lang.Deprecated` and `java.lang.SuppressWarnings` to
> >     allow `ElementType.MODULE` as a target.  For now, no other existing
> >     Java SE annotations will apply to modules.
> >
> > Also, allow `import` declarations [3] to be used in module compilation
> > units.
> >
> >   - Any `import` declarations must appear before the `module`
> declaration.
> >
> >   - As a consequence of supporting `import` declarations, simple type
> >     names can now be used in the `uses` and `provides` directives of a
> >     module declaration.  Type annotations on these type names are not
> >     supported.
> >
> > Rationale
> > ---------
> >
> > When we first discussed this topic I wrote [4]:
> >
> >> We haven't seen a compelling use case (so far) for annotations on module
> >> declarations, or on clauses in module declarations, and they aren't a
> >> documented requirement, so for simplicity we left them out of the
> initial
> >> design and the prototype.
> >
> > The compelling use case is, of course, deprecation, as Rémi pointed out
> > [5].  In Java SE 9, in particular, we very much want to be able to write
> > something like this:
> >
> >     @Deprecated(since = "9", forRemoval = true)
> >     module java.corba {
> >         ...
> >     }
> >
> > The most natural way to do this is to allow module declarations to be
> > annotated in the same way as other top-level declarations (i.e., packages
> > and classes).  If we don't allow the `@Deprecated` annotation to be used
> > on modules then we'd have to invent some other way to deprecate modules
> > (another new keyword?), and that would just be confusing.
> >
> > Like most language features, annotations have sometimes been over-used
> > and even abused [6].  Allowing modules to be annotated opens up a whole
> > new avenue for unfortunate design decisions that lead to unreadable code.
> > We could try to limit the damage by allowing just a few annotations on
> > module declarations (e.g., only those in the `java.lang` package), or by
> > not supporting `import` declarations so that the use of non-platform
> > annotations is discouragingly verbose.  Such an approach would lead to
> > unpleasant asymmetries in the language, however, so instead we propose to
> > support arbitrary annotations on module declarations in the obvious way.
> >
> > I think the guidance I wrote earlier [4] still holds.  Annotations are
> > useful for extra-linguistic statements, such as deprecation, that make
> > sense in source code and can usefully be carried through the tool chain
> > into the resulting class file.  I still don't think they're appropriate
> > for information that is more appropriately the domain of build systems,
> > e.g., version strings.
> >
> > Notes
> > -----
> >
> >   - Should it be possible to annotate the individual directives in a
> >     module declaration?  This would allow you to deprecate individual
> >     exports and requires-public directives, which could be useful in the
> >     process of evolving an API: If you plan to remove a package, or
> >     remove a public dependence upon some other module, then you could
> >     deprecate the corresponding `exports` or `requires public` directive
> >     (presumably with `forRemoval = true`) to warn your users that the
> >     API is going to change.
> >
> > There are no cases in the JDK itself where we need this ability, at least
> > not desperately.  Designing and implementing this would be a non-trivial
> > exercise, and it is a separable feature that could be added later on if
> > justified by experience.
> >
> >
> > [1]
> http://openjdk.java.net/projects/jigsaw/spec/issues/#ModuleAnnotations
> > [2]
> http://openjdk.java.net/projects/jigsaw/spec/issues/#ModuleDeprecation
> > [3] http://docs.oracle.com/javase/specs/jls/se8/html/jls-7.html#jls-7.5
> > [4]
> http://mail.openjdk.java.net/pipermail/jpms-spec-experts/2015-October/000153.html
> > [5]
> http://mail.openjdk.java.net/pipermail/jpms-spec-experts/2016-March/000263.html
> > [6] http://annotatiomania.com/
>