[MDSAL-741] Capture union's stringValue() contract

Blocks — Tue, 9 Jan 2024 09:13:20 +0000

Generated unions provide a stringValue() method, which acts as a utility providing a simple way to get the (mostly) canonical String representation of the union. This method is sorely undocumented and it is not captured in a Binding Spec contract.

There are a few users relying on this functionality, mostly for convenience of transferring the value to somewhere which accepts Strings. The contract is meant to be reversible in that the generated union builder's (removed via ~~MDSAL-49~~) getDefaultInstance() method can parse the string back to the union – but that is not documented and generally not achievable.

Unfortunately JLS lacks a way to specify static methods with an interface contract (like Haskell has), but we need to document at least the instance method contract and specify (via documentation) the expectation of having a static factory method to reconstruct the object.

That static factory method (let's call it ofStringValue(String)) is the crux of ~~MDSAL-49~~: we cannot always provide it due to the infinite extensibility around leafref/identityref/instanceidentifier and Java class visibility rules. We therefore should only provide this contract for unions which are decidedly simple type, e.g. all their constituents boil down to built-in types or ValueObjects with static typing.

OpenDaylight JIRA

[MDSAL-741] Capture union's stringValue() contract