GeezerVison

Steps 1 and 2 of the alternative plan discussed in #461. The commits are separate and each one builds and passes on its own.

1. ci: API compatibility gate

• Adds japicmp-maven-plugin to pom.xml. It isn't bound to any build phase, so a plain local build doesn't need network access.
• Adds a Check API compatibility step to CI. It compares the built jar against the newest non-RC tag before HEAD^.
  • On a release-tag build, that is the release before it, which is already on Maven Central.
• The step fails on any change that breaks callers at compile time or at runtime. The exception is a version in pom.xml with a higher major number than the baseline, as on beta; there the report is for information only.
• The report goes to the job summary.
• japicmp's own semantic-versioning mode can't be used here. Between releases pom.xml still carries the last released version, and in that state the mode rejects even additive changes.
• Documented in CONTRIBUTING.md and AGENTS.md.

2. Internal boilerplate, without changing the public API

• Response parsing. Requests no longer create a model's JsonUtil just to reach the shared Gson. They call ModelObjectJson in a new se.michaelthelin.spotify.internal package.
  • The package isn't exported from the module and doesn't appear in the published Javadoc. It is excluded from the API gate.
  • ModelObjectGson moved there too. The parsing steps are the same, so empty or malformed bodies fail exactly as before.
• Custom readers. The hand-written readers for Disallows, ExternalId, ExternalUrl and PlaybackQueue are now Gson adapters.
  • Their JsonUtil.createModelObject overrides now only call super.
  • They stay because their erased return type differs from the inherited one, so removing them would break callers that are already compiled.
• Assertions. The 92 inline assert (x != null); assert (!x.isEmpty()); pairs in request builders are replaced by Preconditions.assertNotEmpty(x).
  • It is still a Java assertion: a no-op by default, and an AssertionError under -ea, as before (checked both ways).
• Public replacement for JsonUtil. New class se.michaelthelin.spotify.model_objects.ModelObjects, for callers who read JSON they got outside a request, such as cached responses. It has four methods: fromJson, arrayFromJson, pagingFromJson and pagingCursorbasedFromJson.
  • It parses exactly the way the requests do, including enum and date formats and the mixed track/episode playlist items.
  • The signatures take a String rather than Gson types, so they won't be affected if Gson later stops being part of the public API.
  • There are deliberately no key overloads: adding them later is compatible, removing them wouldn't be.
• Deprecation. All JsonUtil classes and IModelObject.IJsonUtil are marked deprecated, point to ModelObjects, and are to be removed in the next major version.
  • It's plain @Deprecated rather than forRemoval. Removal warnings aren't suppressed inside deprecated code, so every model JsonUtil extending the deprecated base class would add a warning to the build.
  • ModelObjectMappingTest now uses ModelObjects.

Verification (local)

• mvn install: 420 tests, all passing, including 6 new ones for ModelObjects.
• japicmp against 10.1.0: only additions, no incompatible change.
• The gate itself was tested in both directions:
  • A public method made package-private fails it.
  • The same break inside an excluded package passes.
• Javadoc (javadoc-check profile), the examples module compile, and ci/check-docs.py: all pass.

🤖 Generated with Claude Code

https://claude.ai/code/session_01KSXwvJcGsHkEQQs7VNmYpR