Legacy classes in a module

[Stanley M. Ho]

Hi JSR 277 experts,

This is regarding the semantic of legacy classes in a module, and is one
of the outstanding issues in the updated specification (Section 2.14)
that I would like to get your inputs.

Typically, classes in a module are "module" classes - Java classes that
have superpackage membership. However, it is also possible that
developers may want to make use of legacy classes in a module, e.g.
using an existing xml parser in a module. There are two possible use
cases I can think of:

1. Developers simply make use of the legacy classes as implementation
details in the module. In this case, the exported module classes neither
expose nor reference the legacy classes in the export signatures, and
the legacy classes in the module should not be made visible to the
importing modules.

2. Developers use the legacy classes as part of the public API in the
module. In this case, the legacy classes in the module should be made
visible to the importing modules. The exported module classes may expose
or reference the legacy classes in the export signatures, but this is
not required.

I think it's important for us to recognize and support both use cases.
However, this may be difficult for us to determine which use case is the
developers' real intention. Adding to the mix is that lack of module
level access control for the legacy classes, and there is not much we
can do once the legacy classes are leaked out from the module classloader.

That said, I think it's still important for us to define the semantics
for both use cases in the specification. Here is what I propose:

a. Consider #1 to be the default.
b. Add a new superpackage-level annotation (e.g. @ExportLegacyClasses)
for developers to indicate the module is in the #2 category.
c. If @ExportLegacyClasses is declared, the
ModuleDefinition.getExportedClasses() would include the legacy classes.

Note that unless this annotation is declared in the module definition,
the importing modules will never attempt to load the legacy classes from
the imported module during classloading delegation as the classloading
delegation algorithm always checks getExportedClassed() first (see
algorithm in 7.3.1, step 4). However, if other code obtains a reference
of the module classloader somehow and invokes loadClass() directly with
the legacy class name, the module classloader will still return the
legacy class, and this is consistent with the existing classloader behavior.

Let me know if you have inputs. If there are better ways to deal with
this issue, I would like to hear them as well.

- Stanley