Internal Package Boundaries & Encapsulation

## The four access levels Java defines four access levels, in increasing order of exposure: | Level | Reach | |---|---| | `private` | the declaring class only | | package-private / default | no modifier — visible to any class whose source file declares the same package, regardless of inheritance | | `protected` | package-private plus visible to subclasses in other packages | | `public` | visible everywhere reachable on the classpath/module path | **Package-private is the only level tied purely to physical file organization** rather than the type hierarchy. When a top-level class, field, method, or constructor has no modifier, `javac` treats any reference from a class outside that exact package as a compile error — no import path resolves it, so the violation is caught before the code ever runs, at zero runtime cost and with no extra tooling. ## Why it exists — information hiding This exists because of **information hiding** (Parnas's principle): a module's public surface should be the minimum needed by its callers, while everything else stays free to change without breaking anyone: - algorithms - data structures - helper classes - caches A package-private helper class (say, a CSV row parser used only by one loader) has exactly one set of callers, all inside the same package, so the author can rename its methods, change its constructor, or delete it outright without a cross-team migration. This is the **cheapest encapsulation mechanism the JVM gives you**: - no config file - no library - no separate build step The compiler enforces it as a side effect of normal compilation. ## The cost — granularity Package-private is all-or-nothing at the package boundary: you can't say "visible to package B but not package C," only "visible to everyone in this exact package or to no one outside it." This bites when a genuinely internal type needs to be shared between two closely related but separately-packaged classes — say `order.internal.PricingEngine` and `payment.internal.DiscountCalculator` both want to use the same internal utility. The choices are then: 1. Make the utility **public**, leaking it to literally everyone, defeating the purpose. 2. Physically **relocate** code into a shared package just to get access, producing a package that exists purely for visibility reasons rather than a coherent design unit. Kotlin's `internal` modifier, scoped to the whole compilation module rather than one package, exists partly to solve this exact granularity mismatch. ## How the boundary erodes In practice, package-private boundaries erode in a few characteristic ways. 1. **First, "temporary" widening.** Under time pressure a developer needing cross-package access marks a class public "just this once," and because nothing forces it back, it becomes permanent, silently-adopted API that later blocks refactoring. 2. **Second, reflection bypass.** Frameworks like Hibernate, Jackson, and Spring routinely call `Field.setAccessible(true)` to read and write package-private and even private fields directly, so package-private is a compile-time social contract between human-written code, not a runtime security boundary — reflective code can always reach in. 3. **Third, pre-JPMS,** package-private wasn't even sealed at the classpath level: two different JARs could declare classes in the same package name, and a maliciously crafted one could add classes to your package and get compiler-level access to your "hidden" members — the split-package problem, one concrete motivation behind JPMS's stronger module-scoped encapsulation. ## Where it shows up — a modular Spring backend A concrete example from a modular Spring backend: a module like `order` exposes exactly one public entry point, an `OrderApi` interface, while its implementation class `OrderService`, its JPA repository, and its internal mapper classes are declared package-private (or, in Kotlin, `internal`) inside `order.internal`. Another module, `payment`, can only call `order` through `OrderApi` — it has no visibility into `OrderService` at all, so the compiler physically prevents `payment` from reaching past the API into order's persistence details. This lets the `order` team change its database schema, its mapper logic, or even swap its persistence technology, as long as OrderApi's contract is preserved. Where compiler visibility alone falls short — some classes must be public for Spring or JPA to instrument them even though they're conceptually internal — teams backstop the convention with an **architecture test**, exactly the gap ArchUnit and `ApplicationModules.verify()` exist to close, which is why package-private visibility and architecture tests are typically used together rather than as substitutes.