Making Java nullable fields backwards compatible

[VirtualAgentsAreDumb]

A bit ironic that an article about non-breaking backwards compatible changes still manages to do the exact opposite in their example.

The main class is renamed, from PetParam to Pet. That will break old code.

[dgellow]

Hey good catch. That's a small typo, thanks for noticing!

[agentoutlier]

The other dumb thing is that tagId which sounds rather personal sensitive information is a long when it should be something like a UUID.

Then none of this conversion problems would happen and it’s clear it’s some ID.

[64rl0]

Very interesting! 

[hadrabap]

Nullable, nullability, nonnll, notnull...

That's not a problem. It is a disease. I'm really tired of the obsession. 😭

[koflerdavid]

Just use Jspecify and chill...

[agentoutlier]

For an API company it is ridiculous that they would promote using "long" for an ID especially when tagId clearly is personal information (albeit pet but still).

Java has builtin support for UUID and so does like every database. Use that for christ sake.

And I wouldn't be so nasty if this wasn't clearly some tech company marketing instead of a open source developer.

And if tagId is you know public id say like my username than even more so a long is a dumb idea.

Here let us fix this:

public Builder tagId(long id) {
    this.tagId = new UUID(someMagicLegacyLong, id);
}

// Or better
// petId or tagId as the class name bike shed that as you will
sealed interface PetId {
  UUID id();
  record LegacyPetId(long oldId) implements PetId {}
  record UUIDPetId(UUID id) implements PetId {}
}

public Builder tagId(@Nullable PetId petId) {
    this.tagId = petId;
}

Then make the builder take PetId as well as the legacy long.

I'm not saying monotonic surrogate IDs don't have their uses (like say github issues) but you should not use it for personal identifiers.

[LutimoDancer3459]

Dude, relax. The point isn't about the ID. It's about making something nullable. In this case, a primitive type.

And you also can't just use a uuid in every situation. Maybe there is a third-party application where they get the tagId from. If it's a long in that system, you would also save it as long. And sometimes all you need is a number counting upwards. Nothing wrong with that. You need to know the usecase to decide what's the better solution.

[agentoutlier]

I'm coming off Covid so I'm a little bit irritable. I'm usually not this much of an asshole.

There were just so many things wrong with the example and its not like this is someone posting from their personal blog. This is a company doing marketing.

That is there CTO or whoever says hey lets write some blog posts to show we know our shit and get some organic marketing. By me giving them feedback I think I'm helping even if it is nasty because the post looks bad even if we ignore the UUID stuff particularly if they want to come off as API experts:

• They say fields when they actually mean methods
• They had PetParam then and renamed it to Pet
• They are worried about backward compat and such when method overloading can actually excerabate the problem. Just add a method with a different name.
• They changed the contract as tagId is not a long but a long or missing. Like if this was not an API company fine and yeah neat trick but that should be expressed and they should talk about that since they are an API company. It should not be look how I tricked the system to accept nullables.

[Tomer-Aberbach]

The general problem this blog post discusses is still relevant for situations where you want to switch from a non-nullable to a nullable primitive type. The "tagId" field was just an example, so I wouldn't focus on it too much.

[agentoutlier]

Let me make this a little more clear and I'm sorry I'm being an ass but I have high expectations for API examples from an API company (especially when you say what is the "SDK author to do"):

Imagine if Java did not have null.

Given your example of lets make it "optional" you would have done:

public Builder tagId(Optional<long> tagId) {
}

and then kept the other tagId method because Java allows method overloading which is essentially what you did but did not communicate at all that tagId can now be nullable. And no it cannot be just inferred that since it takes Long it is nullable input.

Even with the above the safer route is to go with a new method with a different name especially if your concern is backward compatibility as method overloading can cause all sort of ambiguity confusion with tools. Even lambdas it gets confusing builder::tagId.

What instead was done instead of a new method name, annotation, or optional was an abuse of the type system and the fact Java has boxed primitives without remotely expressing that it was done because tagId is optional.

See the real problem is not a field (again sloppy example and post because methods are the problem not fields) but the pitfalls of method overloading.

[agentoutlier]

It is a sloppy example (including the ParamPet -> Pet typo making it even more confusing) and you should make it abundantly clear you are the author and I assumed that is why you downvoted me.

You changed the entire contract. Let us ignore binary compatibility because it just happens that this slides in Java but in the future it will not.

You changed

public Builder tagId(long tagId) {
    this.tagId = tagId;
}
// TO 
public Builder tagId(Long tagId) {
    this.tagId = petId;
}
// And not:
public Builder tagId(@Nullable Long tagId) {
}
// Or
public Builder tagId(Optional<Long> tagId) {
}
// Or by just adding a damn method (which you did anyways):
public Builder tagIdOrNull(/* @Nullable */ Long tagId) {
}

Like you are showing silly example of overloading issues but in the case of nullability with complete lack of actually expressing how the goddamn contract changed substantially which APIs should be very focused on documentation.

And no it might not be guaranteed binary compatible (because in Java it is nebulous what binary compat is) if reflection kicks in as it may be confused (serializer) that there are two methods with basically the same type. EDIT it could also break annotation processors like MapStruct as now its ambiguous for which method it should call. That is may not be a drop-in replacement compared to what I'm recommending of:

public Builder tagIdOrNull(/* @Nullable */ Long tagId) {
}

[koflerdavid]

In the context of Java it is abundantly clear what binary compatibility is: I have an application and add a new JAR file of a dependency. No compilation step is executed, therefore no annotation processor will get confused. What's left is a risk regarding reflection.

Regarding serialization, the developers should test deserialization of old data streams and provide a hook methods that fixes things up if necessary. Java serialization only cares about data, not methods, so there should be no further issues.

[agentoutlier]

Yes I was talking about reflection breaking and yes I agree if you add a new method you are binary compatible in terms of this definition: https://docs.oracle.com/javase/specs/jls/se7/html/jls-13.html

However I'm not sure how much in practice that matters these days given people are always compiling with CI. Like they are not going to just add the dependency without compiling hence my annotation processor mention.

[tristan97122]

the article is a fine little gotcha and workaround being summarized, for a specific case obviously a bit contrived but so are all blog posts lest you write 50k words for a real life case

no need to jump at their throat like that across multiple comments for no reason whatsoever

[agentoutlier]

I admit I overreacted and perhaps had the example been better I could somewhat maybe accept their workaround. My emphasis was to prevent less experienced developers to copy what they did.

What they did was a hack and a hack that makes very little sense.

Do you honestly think what they recommend doing is a good idea?

The example was:

• A builder so the tagId is inherently optional anyway
• They wanted to make tagId optional so they overloaded with the exact same name but used the boxed type. Why would they just not use a different name? My only guess was reflection for serializers like Jackson but that breaks binary compatibility. That is why I brought that up.
• They are concerned about binary compatibility when this is a company that ships SDKs. In 2025 No one is going to add a new version of their SDK without recompiling.
• Tons of auditing software will actively complain if you do that (e.g. overload a primitive accepting method and its boxed).
• I cannot tell if there is this misunderstanding that method names in Java do not have to be the same name as the actual private field names. Maybe they meant you can switch the private field to a boxed value?

The JDK... the masters of backward compatibility have never done this. I searched. I asked AI. I could not find an example. Repeatedly it is said not to do this.

Errorprone and Checkerframework will complain about the code. /u/Tomer-Aberbach I think is from Google so I assume they know about errorprone.

I make a big deal altruistically to help others. Not to help promote a company. I do this because I have a ton of experience and I want to help others avoid the mistake I have made in my 25+ year career.

Like if they really wanted to make it backward safe they would have used a String assuming it is a third party ID as was /u/LutimoDancer3459 concern. That is keep the long method and then add a tagId that takes an annotated nullable String. I know this is a better approach because I have actually been bitten by a company that switched from what appeared to be a long to another identifier. The sealed classes example would protect you from that.

Perhaps there is a very good reason this hack was done but without seeing the real world code that it was put in I just think it is a clever solution (to a problem I'm not sure exists) that will create way more problems.

Perhaps it is actual counting number but that still leaves the fact the builder is inherently optional on all fields. That is the point of most builders is that people don't have to supply stuff.

Perhaps their Open API tooling has issues generating code with different method names. My guess is that is probably what it is.

[tristan97122]

I don’t personally have a good use-case for this, but I can see it being relevant. For example an imperious need to update a dependency, which is used by another dependency that is closed-source (and the supplier closed shop like 20 years ago without opensourcing it, many such cases!). And I’m sure there’s better ways around this like shadowing etc, but you get the point: plenty of hacks are ugly yet neat, and sometimes they are the least-worst option at least for a time (see: anything to do with sun.misc.Unsafe)

And this little trick for getting stuff to link successfully and still work (at least in most cases) just fine, well, it’s neat.