Small JBang programs that put the findings of the revapi reports to the test.

Each example is written against the FROM version of a <FROM>_<TO> report folder and exercises an API that the TO version changed in an incompatible way. The contract of every example in this folder is:

• it compiles with //DEPS com.unblu.openapi:jersey3-client-v4:<FROM>
• it does not compile any more when that line is changed to <TO>

An example that compiles with both versions does not demonstrate anything and is not kept here.

The header comment of each example names the report folder and the revapi finding codes it targets, so a finding can be traced from the report to the code that breaks on it.

Only the v4 API is covered. models-v4 is a transitive dependency of jersey3-client-v4, so examples targeting a models-v4 finding also declare jersey3-client-v4 as their dependency.

Every example takes the same arguments:

./SomeExample.java <server> --superadmin <username> --password <password>
./SomeExample.java <server> --admin <username> --password <password>

where <server> is the url of the collaboration server including the web application path, for example https://unblu.example.com/app. Whether an example needs a super admin or an account admin is stated in its header comment and in the table below.

The argument parsing lives in Util.java, which every example pulls in with //SOURCES Util.java. It uses no type of the generated client, so that the same file works for every client version.

34 programs covering every one of the 593 SOURCE/BINARY: BREAKING findings in the reports. "Findings" is how many that example is the primary cover for; "Runs" says whether it completes against a current server.

* the request is accepted, but a current server ignores the autoOpen value and returns it as null.

Every example that builds a client calls

Util.applyRecommendedDeserialization(client.getJSON().getContext(null));

which sets FAIL_ON_UNKNOWN_PROPERTIES=false and READ_UNKNOWN_ENUM_VALUES_AS_NULL=true. Without the second one, several of these examples cannot run at all: the generated enums are closed, so a value added to an enum after the client was generated makes the whole response fail to deserialize rather than just that field. ConversationsApiWithExpandParameter is the clearest case — every conversation payload carries a link type that did not exist in 8.0.1.

The clients set both flags themselves from 8.13.1 onward, so the call is a no-op for the newer examples and is what makes the older ones runnable. Note that the setting discards the unknown value rather than recovering it, so code that reads an enum has to be ready for null, and code that round-trips data can silently write the null back.

Four of the 34:

• GenerateSummaryTryForTemplate, SearchCannedResponsesByKey, SearchPersonsByLabelName — the value each one sends was removed from the set the server accepts at the same time as from the client, so the request comes back 400. Nothing on the client side can fix that; the failure is the finding.
• InstallLicenseWithExpandParameter — installing or removing a licence changes what the whole server may do. Never run it against a shared environment.

Their compile contract is verified in both directions like every other example, which is what they are here for.

There is no script for this yet. To check an example by hand, build it as it is, then build a copy with the TO version substituted in its //DEPS line:

jbang build CreateTeamWithExpandParameter.java                 # must succeed

sed 's|jersey3-client-v4:8.0.1|jersey3-client-v4:8.1.2|' \
    CreateTeamWithExpandParameter.java > /tmp/Broken.java
cp Util.java /tmp/
jbang build /tmp/Broken.java                                   # must fail

• Name the file after what it does, not after the versions it compares.
• Keep the cognitive complexity low: one linear main method, private helpers for the set-up of the request bodies. Being long is fine, being clever is not.
• Follow the same shape as the existing examples — create, read back, delete — so that a run leaves no leftovers on the server.
• Everything in this folder is public. Use no real host names, no real credentials, no customer names and no real person names. Example Company, example.com addresses and https://unblu.example.com/app are the placeholders used throughout.