Lots of valuable answers already, but I'd like to stress the importance of modelling unknown information:

For the "someInt" information that gets represented in that field, is there a notion of "I don't know the value"? E.g. if "someInt" is "age", then "unknown" should always be distinguishable from "0 years", and none of the APIs should hide that distinction.

Your SomeEntity class having an Integer field instead of an int hints at that, and the "@deprecated Maps nulls to zero" also supports that interpretation.

But getInt() methods come in handy in some cases: for example, when we need to pass zero for newly persisted entities.

There's the problem (if my interpretation is correct). The "need to pass zero" breaks the model, as it would falsely declare e.g. the newly-persisted person to be a new-born baby instead of an unknown-age person.

Information Technology is all about handling information, and not having some information is quite normal, it happens all the time. So our modelling should almost always include some representation of "unknown" and be careful not to confuse it with some other, possibly valid value.

Lots of valuable answers already, but I'd like to stress the importance of modelling unknown information:

For the "someInt" information that gets represented in that field, there seems to be a notion of "I don't know the value". E.g. if "someInt" is "age", then "unknown" should always be distinguishable from "0 years", and none of the APIs should hide that distinction.

Your SomeEntity class having an Integer field instead of an int hints at that, and the "@deprecated Maps nulls to zero" also supports that interpretation.

But getInt() methods come in handy in some cases: for example, when we need to pass zero for newly persisted entities.

There's the problem (if my interpretation is correct). The "need to pass zero" breaks the model, as it would falsely declare e.g. the newly-persisted person to be a new-born baby instead of an unknown-age person.

Information Technology is all about handling information, and not having some information is quite normal, it happens all the time. So our modelling should almost always include some representation of "unknown" and be careful not to confuse it with some other, possibly valid value.

It's of minor importance how you represent "unknown". Older Java code typically uses null, later the Optional class became popular. I'd only stay away from "out-of-range" special values, e.g. -1 for unknown.

Besides, replacing getInt() with getIntNullable() may cause (and did cause) NPEs on unboxing. Those kinds of issues can sometimes be tricky to spot and may not immediately emerge.

It's important to spot these bug places where a consumer of your class falsely assumes that someInt has a known value, ignoring that it can be unknown. And that's the advantage of Optional: it's easier to spot the places where a consumer tries to access the value.