12.3 Reflection, Deep Encapsulation, `opens`, and Open Modules

Reflection, Deep Encapsulation, opens, and Open Modules

Reflection has long been a cornerstone of enterprise Java frameworks, powering dependency injection containers (Spring, CDI), object-relational mapping engines (Hibernate), and serialization libraries (Jackson, GSON). Prior to Java 9, reflective code could invoke AccessibleObject.setAccessible(true) on any Field, Method, or Constructor to bypass standard access control checks (private, protected, package-private). In Java 17 LTS, deep encapsulation is strongly enforced by default, requiring explicit module descriptors to authorize reflective access.

---

Deep Encapsulation Barriers in Java 17

Under Java 17, the JVM strictly differentiates between compile-time accessibility and runtime reflective access:

• Shallow Accessibility: Access to public types and public/protected members for direct invocation. Granted via the exports directive.
• Deep Reflection: Access to private, package-private, or protected members via setAccessible(true). Blocked across module boundaries by default.

Why exports Alone Forbids Deep Reflection

A frequent misconception is that exporting a package opens it to reflection. If a module exports a package using exports com.example.model;, consuming modules can compile against and invoke its public members. However, if a framework attempts to inspect or mutate a private field via reflection:

// Inside a consuming module:
Class<?> clazz = Class.forName("com.example.model.Account");
Field balanceField = clazz.getDeclaredField("balance"); // private double balance;
balanceField.setAccessible(true); // THROWS EXCEPTION!

The JVM blocks the operation and throws:

java.lang.reflect.InaccessibleObjectException: Unable to make field private double 
com.example.model.Account.balance accessible: module com.example.billing does not 
"opens com.example.model" to unnamed module @5b2133b1

The opens Directive

The opens directive is designed specifically to grant reflective access to a package at runtime without exposing it at compile time:

module com.example.billing {
    requires java.sql;
    opens com.example.billing.entities;
}

Key Characteristics of opens:

1. Runtime Reflection Only: An opens directive does not export the package for compile-time access. Other modules cannot write import com.example.billing.entities.User; in their source files. Attempting to do so triggers a compile-time error.
2. Deep Reflective Access: At runtime, any module that reads com.example.billing can invoke setAccessible(true) on private, package-private, protected, and public members of types in com.example.billing.entities.
3. Combining exports and opens: A package can be simultaneously exported (for public compile-time APIs) and opened (for framework reflection):

   module com.example.billing {
       exports com.example.billing.dto; // Public types accessible at compile time
       opens com.example.billing.dto;   // Deep reflection permitted at runtime
   }
   

---

Qualified Opens (opens ... to)

Granting unrestricted reflection to all modules can create security vulnerabilities. To mitigate this risk, JPMS provides qualified opens, which restrict deep reflection to specific designated consumer modules:

module com.example.service {
    opens com.example.service.model to org.hibernate.orm.core, com.fasterxml.jackson.databind;
}

In this declaration:

• Only Hibernate and Jackson are permitted to invoke setAccessible(true) on private members within com.example.service.model.
• Any other module attempting deep reflection on this package receives an InaccessibleObjectException at runtime.
• The package remains completely hidden from compile-time imports across all modules.

---

Open Modules (open module)

When developing entity-heavy applications or migrating enterprise microservices, specifying individual opens directives for dozens of model packages becomes tedious. JPMS provides the open module syntax to open an entire module at once:

open module com.example.portal {
    requires java.sql;
    exports com.example.portal.api;
}

Rules Governing Open Modules:

1. All Packages Opened: Every package in an open module is automatically opened for deep reflection at runtime, including packages created dynamically or added in subsequent builds.
2. Selective Exporting: Packages within an open module are not automatically exported for compile-time access. You still use explicit exports directives to declare which packages form the public compile-time API.
3. Prohibition of opens Inside an Open Module: Because every package in an open module is already open, declaring an opens directive inside an open module produces a compile-time error:

   open module com.example.portal {
       // COMPILE ERROR: 'opens' only allowed in strong modules
       opens com.example.portal.internal;
   }
   

---

Comparison: exports vs. opens

The following matrix contrasts the capabilities and rules of exports and opens directives:

---

CLI Flags and Programmatic Reflection Overrides

During testing or when transitioning legacy libraries that cannot be recompiled with modular descriptors, developers can dynamically modify module boundaries at JVM launch:

• --add-opens <module>/<package>=<target-module>: Dynamically opens a package to a designated module (or ALL-UNNAMED for tools running on the classpath) for deep reflection at runtime without editing module-info.java.
• --add-exports <module>/<package>=<target-module>: Dynamically exports a package to a designated module or ALL-UNNAMED, granting public access to types at compile time or runtime.

Inspecting Module Boundaries via java.lang.Module

Java provides runtime reflection over the module graph via the java.lang.Module class:

Module myModule = getClass().getModule();
boolean isModelOpen = myModule.isOpen("com.example.billing.entities", frameworkModule);
boolean isApiExported = myModule.isExported("com.example.billing.api");
boolean readsSql = myModule.canRead(javaSqlModule);

These programmatic inspection methods allow runtime frameworks to verify that appropriate opens or exports directives have been configured before initiating deep reflective binding operations.