java-language-design

To design idiomatic Java APIs, enforce explicit mutability boundaries and narrow public surfaces. This approach ensures clear contracts and maintainable class structures using records, sealed types, and proper exception boundaries.

Use Java records for transparent data carriers and sealed classes when you need restricted hierarchical structures. This distinction helps enforce explicit value semantics and narrow public surfaces in your API design.

The best way to handle checked vs unchecked exceptions in Java public APIs is to enforce clear exception boundaries. Use checked exceptions for recoverable conditions and unchecked exceptions for programming errors to shape robust public contracts.

Review a Java class structure by analyzing its public surface and applying idiomatic design guidance. Enforce explicit mutability boundaries by refactoring to records or sealed types and narrowing exposed state.

Refactoring Java APIs for immutability does not require external frameworks. It relies on native language features like records, sealed classes, and visibility modifiers to establish explicit mutability boundaries and narrow public surfaces.