HDDS-16127. Document OmKeyInfo key location version semantics

[chihsuan]

What changes were proposed in this pull request?

Document the existing OmKeyInfo.keyLocationVersions behavior:

• Bucket versioning can retain multiple location groups in one OmKeyInfo.
• For a committed key, dataSize contains only the latest version size.
• Metadata written before HDDS-5472 may contain earlier blocks in later groups, so callers accounting for all versions should use getBlocksLatestVersionOnly().
• HDDS-15728 object versioning stores each object version in a separate OmKeyInfo.

This is a documentation-only change.

What is the link to the Apache JIRA?

https://issues.apache.org/jira/browse/HDDS-16127

How was this patch tested?

mvn -pl :ozone-common compile -DskipShade -DskipRecon -DskipDocs
git diff --check

Generated-by: Claude Code (Opus 5)

[smengcl]

It looks like the current write path can create more than one location group.

testOverWriteKeyWithAndWithOutVersioning enables versioning, overwrites a key through the client, and verifies that keyLocationVersions has two groups.

dataSize contains only the latest version’s size. Therefore, quota repair can undercount used space.

HDDS-15728 proposes a future layout, but it does not remove the current path. Pls remove this statement, or handle multiple groups.

[chihsuan]

Thanks for the review! @smengcl

You're right, the wording rules out a case testOverWriteKeyWithAndWithOutVersioning actually reaches, so it does need to change. I'll reword it to describe the versioned-bucket case rather than deny it.

On handling multiple groups, I'd like to check with you before going that way. Fixing the active-table recount on its own would still leave snapshotUsedBytes collapsing (HDDS-16184) and leave repair and delete disagreeing on the same key (HDDS-16178), and the EC formula question in HDDS-16176 may well change the conversion again, so it seems to grow into a set of four rather than a single fix. Since no write path exercises versioning today, I leaned toward documenting it accurately for now, but I'm happy to take on the whole set if you feel it's worth doing properly. What do you think?

[smengcl]

Thanks @chihsuan . Let's just document it properly atm.

[chihsuan]

Thanks @smengcl I’ve updated the Javadoc and PR description accordingly. 🙏