Review request on the optional modules support

[Mandy Chung]

  On 08/09/11 10:27, Sean Mullan wrote:
> Hi Mandy,
>
> I was just reviewing the design note (not the webrev) and I had a couple of
> minor comments -
>
> Optional Module
>
> first sentence, suggest:
>
> s/referred as optional module/referred to as the optional module
>

Fixed.

> 2. ModuleNotPresentException
>
> "if it's absent, a ModuleNotPresentException as in the "foo" module example
> given above."
>
> I could not find the "foo" module example above. Do you mean the one at the end
> of the document?
>

I moved the section and the example to the end but forgot to update the 
statement.  Sorry about that.  Will fix that.

> JDK Optional Dependenceies
> 1. APIs that throw ModuleNotPresentException
>
> Are those really the only APIs that require optional modules?

No. They are the ones I identified that should throw 
ModuleNotPresentException when they are called but the optional module 
is missing.  I also suggest that 
javax.management.remote.JMXConnector.connect() and/or 
RMIConnector.connect should be updated to throw 
ModuleNotPresentException as described in the optional.html note.

> Aren't there also
> internal APIs that have optional dependencies? Don't they need to be updated as
> well?
>

There are APIs that have optional dependencies but they are designed to 
work in the absence of the optional module as well.

There are different kinds of optional dependencies.
1. APIs that throw ModuleNotPresentException

It's the caller's responsibility to make sure that the optional module 
is installed.  The APIs have to detect if the optional module exists 
before referencing any type in it.

2. Optional dependencies satisfied by its input arguments

These APIs do not require the optional module to be present unless its 
input arguments specify it and are constructed in in the presence of the 
optional module.  For example,  java.text.Bidi references 
java.awt.TextAttribute.  So the base module should have an optional 
dependency on "desktop" module (it's one clean up task to fix 
module-info.java on my todo list).   The desktop module is guaranteed to 
be present when it hits the code path to reference the 
java.awt.TextAttribute class. In this case, the application should be 
configured properly.

3. APIs that fall back to the default implementation when the optional 
module is absent

ResourceBundle is a good example that falls back to use the default 
locale.  Security provider is another example where the default provider 
and the interface are in one module whereas other provider 
implementation is in another module (note that this doesn't use the 
java.util.ServiceLoader mechanism). In any case, one module has an 
optional dependency on another but it will work both ways - the optional 
module is present or absent.

I see this possibly be adjusted to use the module-aware service loader 
mechanism [1].  In any case, this doesn't throw MNPE.

> General Question
>
> I'm not sure if this question makes sense, but what happens in the future if
> JAXP is required by the base module?

Good question.  @RequireOptionalModule is intended to mark certain 
functionality that requires an optional module but not the rest of the 
module.  If the optional dependency becomes a hard dependency, it makes 
sense to me to update the spec and implementation to remove @ROM 
annotation and @throw MNPE which doesn't have compatibility issue.

> Would it still make sense to annotate APIs
> in the module that require it as an optional module?
>

@RequireOptionalModule is intended for documentation purpose and any 
developer tools to help the developers  be aware that the APIs in (1) 
above requires a specific module to be present.   APIs in (2) and (3) 
above are of a different category that these APIs supports both cases 
when the optional module is present or absent but @ROM is defined for 
those who throws MNPE.  On the other hand, should we have a different 
annotation?

I raised a similar question in my first post of the optional modules 
support [2] what can help the implementor of these APIs to detect if all 
optional dependencies are properly declared in the module-info.java.  
One potential problem I see for APIs in (2) and (3) above is that the 
optional dependency is not declared in the module-info.java and I asked 
if we should annotate all these APIs so that a tool can detect any 
incorrect module-info.java during development.   I convinced myself that 
it's not justified to annotate them for this purpose.  During 
development, tests should be developed to exercise the path when the 
optional module is present or absent and catch the case if the optional 
module is not declared in the module-info.java.   That's my view and it 
should be caught during the development and testing process.

Mandy

[1] http://openjdk.java.net/projects/jigsaw/doc/topics/services.html
[2] http://mail.openjdk.java.net/pipermail/jigsaw-dev/2011-May/001298.html