What is the Java Platform Module System (JPMS), and what do the module-info.java directives do?

// module-info.java at the root of the com.bank.payments module
module com.bank.payments {
    requires com.bank.audit;           // dependency
    exports com.bank.payments.api;     // public surface
    opens com.bank.payments.model to com.fasterxml.jackson.databind; // reflection
}

# Compile a modular project
javac -d out --module-source-path src $(find src -name "*.java")

# Run a modular project
java --module-path out -m com.bank.payments/com.bank.payments.Main

// Before JPMS: any code could use internal helpers
import com.bank.payments.internal.ValidationHelper; // worked on classpath

// After JPMS: this import fails at compile time because the package is not exported
// error: package com.bank.payments.internal is not visible

// Full module descriptor for the bank's transfer service
module com.bank.transfer {
    // Dependencies
    requires com.bank.audit;                    // regular dependency
    requires transitive com.bank.model;         // re-exported to readers of this module
    requires static com.bank.annotations;       // compile-time only

    // Public surface
    exports com.bank.transfer.api;              // visible to all modules
    exports com.bank.transfer.spi to com.bank.reporting; // visible only to reporting

    // Reflection access
    opens com.bank.transfer.entity to org.hibernate.orm.core; // Hibernate can reflect

    // Service wiring
    provides com.bank.spi.FeeCalculator with com.bank.transfer.GstFeeCalculator;
    uses com.bank.spi.AuditSink;
}

package com.bank.payments.api;

import java.math.BigDecimal;

public class TransferService {
    /**
     * Transfer money between accounts at National Bank of India.
     * This class is in an exported package, so other modules can use it.
     */
    public BigDecimal transfer(String fromAccount, String toAccount, BigDecimal amount) {
        // Delegates to internal validator (not exported)
        return amount;
    }
}

package com.bank.payments.internal;

// This class is in a non-exported package.
// Other modules CANNOT see it, even though it is public.
public class TransferValidator {
    public boolean validate(String accountId) {
        return accountId != null && accountId.startsWith("SAV");
    }
}

// On the classpath: reflection works on any class
import java.lang.reflect.Field;

public class ClasspathReflection {
    public static void main(String[] args) throws Exception {
        // This worked on the classpath but fails under JPMS
        // unless the package is opened
        Class<?> clazz = Class.forName("com.bank.payments.internal.TransferValidator");
        Field[] fields = clazz.getDeclaredFields();
        for (Field f : fields) {
            f.setAccessible(true); // throws InaccessibleObjectException under JPMS
        }
    }
}

import java.lang.reflect.Field;

public class ModuleReflectionError {
    public static void main(String[] args) throws Exception {
        // Attempting deep reflection into a non-opened package
        Class<?> clazz = Class.forName("com.bank.payments.internal.TransferValidator");
        Field field = clazz.getDeclaredField("maxAmount");

        // This throws java.lang.reflect.InaccessibleObjectException:
        // Unable to make field private java.math.BigDecimal
        // com.bank.payments.internal.TransferValidator.maxAmount
        // accessible: module com.bank.payments does not "opens
        // com.bank.payments.internal" to unnamed module
        field.setAccessible(true);
    }
}

Exception in thread "main" java.lang.reflect.InaccessibleObjectException:
  Unable to make field private java.math.BigDecimal accessible:
  module com.bank.payments does not "opens com.bank.payments.internal"
  to unnamed module

java --add-opens com.bank.payments/com.bank.payments.internal=ALL-UNNAMED \
     -m com.bank.app/com.bank.app.Main

// Service interface in com.bank.spi module
package com.bank.spi;

import java.math.BigDecimal;

public interface FeeCalculator {
    BigDecimal calculateFee(BigDecimal transactionAmount);
}

// Provider module declares the implementation
module com.bank.fees {
    requires com.bank.spi;
    provides com.bank.spi.FeeCalculator
        with com.bank.fees.GstFeeCalculator;
}

// Consumer module loads the service
module com.bank.transfer {
    requires com.bank.spi;
    uses com.bank.spi.FeeCalculator;
}

package com.bank.transfer.api;

import com.bank.spi.FeeCalculator;
import java.math.BigDecimal;
import java.util.ServiceLoader;

public class TransferService {
    private final FeeCalculator feeCalculator;

    public TransferService() {
        this.feeCalculator = ServiceLoader.load(FeeCalculator.class)
                .findFirst()
                .orElseThrow(() -> new IllegalStateException("No FeeCalculator found"));
    }

    public BigDecimal transferWithFee(String from, String to, BigDecimal amount) {
        BigDecimal fee = feeCalculator.calculateFee(amount);
        BigDecimal total = amount.add(fee);
        System.out.println("Transfer " + amount + " + fee " + fee + " = " + total);
        return total;
    }
}

# Build a custom runtime for the transfer service
jlink --module-path out:$JAVA_HOME/jmods \
      --add-modules com.bank.transfer \
      --output transfer-runtime \
      --strip-debug \
      --compress zip-6

# The result is often 40-60 MB instead of the 300+ MB full JDK
du -sh transfer-runtime/
# 48M  transfer-runtime/

# Run from the custom runtime
transfer-runtime/bin/java -m com.bank.transfer/com.bank.transfer.Main

Docker image sizes:
  Full JDK base:      ~340 MB
  jlink custom image:  ~48 MB
  Savings:             ~86%

// WRONG: Hibernate cannot reflect into entity package
module com.bank.app {
    requires org.hibernate.orm.core;
    exports com.bank.app.entity; // exports is not enough for reflection
}

// Error at runtime:
// org.hibernate.MappingException: Could not get constructor for
// com.bank.app.entity.Account

// CORRECT: open the package for deep reflection
module com.bank.app {
    requires org.hibernate.orm.core;
    exports com.bank.app.entity;
    opens com.bank.app.entity to org.hibernate.orm.core; // reflection allowed
}

// Error at startup:
// java.lang.module.ResolutionException:
// Modules com.bank.core and com.bank.legacy both export package
// com.bank.model to module com.bank.app

package com.bank.transfer.api;

import java.math.BigDecimal;

public class TransferDemo {
    public static void main(String[] args) {
        // Print the module this class belongs to
        Module mod = TransferDemo.class.getModule();
        System.out.println("Module name: " + mod.getName());
        System.out.println("Is named:    " + mod.isNamed());

        // List all packages exported by this module
        ModuleDescriptor desc = mod.getDescriptor();
        if (desc != null) {
            desc.exports().forEach(e ->
                System.out.println("Exports: " + e.source())
            );
        }
    }
}

Module name: com.bank.transfer
Is named:    true
Exports: com.bank.transfer.api