Changing Java Members from Public to Package-Private Breaks External Access

Direct Answers

1. Yes, a major version bump is required. Changing a member from public to package-private is a binary-incompatible change. Existing compiled callers will throw IllegalAccessError at runtime. Under semantic versioning this mandates incrementing the MAJOR version (e.g., 1.2.3 → 2.0.0).
2. Use both package-private and strong module encapsulation. Package-private restricts compile-time access within the same package. Java 9+ modules add a runtime boundary: if the package is not exported or opened in module-info.java, reflective access (including setAccessible(true)) is also blocked. For defense-in-depth, keep internals package-private and do not export the package.
3. Detect external dependencies before release with static analysis. Run jdeps --jdk-internals --recursive --class-path '...' on downstream projects, or use animal-sniffer-maven-plugin / japicmp to compare API signatures between versions. IDE inspections (IntelliJ "Access can be package-private") and Error Prone's PackagePrivateAccess check also flag external usages at build time.

Why This Is a Breaking Change

The Java Language Specification defines package-private (default) access as visible only within the same package. Removing public changes the class-file access_flags from ACC_PUBLIC to package-private. Any already-compiled caller that references the member will fail with IllegalAccessError when the JVM resolves the symbol at runtime. This is a binary incompatibility, not just a source incompatibility, so consumers must recompile.

Module Encapsulation Is a Separate Layer

If the library has a module-info.java, the package containing the internal classes should be omitted from exports and opens clauses. Strong encapsulation then prevents reflective access even if a caller uses setAccessible(true). Without a module descriptor (automatic module or classpath), package-private alone does not stop reflection. Therefore, combine both: keep the member package-private and ensure the package is not exported.

Migration Path for Consumers

If you control the library and want to soften the break, provide deprecated public wrappers that delegate to the new package-private implementation:

@Deprecated(forRemoval = true, since = "2.0")
public void oldPublicMethod() {
    internalPackagePrivateMethod();
}

This allows existing callers to compile against the new major version while receiving deprecation warnings. Remove the wrappers in the following major release.

Verification Steps Before Publishing

1. Compile a test consumer against the old JAR, then replace the JAR with the new version without recompiling. Expect IllegalAccessError on first access.
2. Run japicmp --old old.jar --new new.jar and confirm it reports BINARY_INCOMPATIBLE with visibility-decrease messages for each changed member.
3. Enable Error Prone in the consumer build: -Xep:PackagePrivateAccess:ERROR. It should fail on any remaining references.
4. If modularized, run java --describe-module <module> and verify the package is absent from exports and opens.

One Diagnostic Detail Needed

Is the library already modularized (i.e., does it have a module-info.java)? If yes, the module system can enforce the boundary at runtime; if no, you rely solely on package-private and must accept that reflection can bypass it.