Example Java 9 module definition with explanations

module-info.java

/*
Modules are not required, although usage is encouraged. This allows existing code to work within Java 9.
Code defined outside of a module is put in an `unnamed module`
Unnamed is a special module that is able to read from *all* other modules, *but* only the exported code (see below)
All of this is automatic when your code compiles. It allows your existing code to continue working as expected.

This is an example `module descriptor`.
It should be placed directly under the `src` dir, e.g. for in Maven `src/main/java/`
Must be named `module-info.java`.
*/
module foo.helloworld {                         // names must be unique
                                                // `module` is not a reserved word, so can still be used in source code

    requires java.base;                         // implicit

    requires public java.xml;                   // transitive dependency, allow dependents to use types in java.xml
                                                // without requiring it in their module definition

    exports helloworld;                         // classes in this package are available for dependents to use
                                                // normal Java accessibility rules still apply (e.g. private, default, protected, public)
                                                // so only public types are available to dependents
                                                // but only if it's in an exported package

    exports helloworld.support;                 // subpackages are not exported, they need to be explicitly exported

    exports helloworld.impl to bar.helloworld;  // qualified export, export this package to the specified module only
                                                // usage is discouraged, can be useful for sharing internal impls between
                                                // a group of related modules
                                                // encapsulation anti-pattern

                                                // How does Java bar (an external module)? You need to specify in the `module path`:
                                                // javac
                                                // --module-path <path>, -p <path>
                                                //      Specify where to find application modules
}