[JDO-683] Allow version field/property to be visible to application

• Type: Improvement
• Status: Open
• Priority: Major
• Resolution: Unresolved
• Affects Version/s: JDO 3.1-rc1
• Component/s: api
• Labels: jdo jdouserexception optimistic transactions version
• Assignee: Unassigned
• Reporter: Matthew T. Adams
• Created: 26/Aug/11 17:12
• Updated: 29/Aug/11 14:50

Description

Currently, it requires a vendor extension to make the version attribute (field or property) of a PC visible to the application. Some knowledgeable applications may need not only read access to the version field, but also write access to it.

I propose that we allow version metadata to specify that a version attribute be application-visible. For annotation-based metadata, I recommend that it be allowed to be placed on fields & methods. For XML metadata, add XML attributes "attribute-name" to the "version" element that allows the user to specify which field or property is to hold the application-visible version value.

Along with this change would be verbiage in the spec noting that applications really shouldn't change this value, but a knowledgeable application may change it, based on a new PMF & PM property called something like "javax.jdo.option.OnVersionChangeByApplication" with the following specified values.

THROW: (default) the implementation will throw JDOUserVersionChangeException (extends JDOUserException) as early as the time the value is set, at the next flush, or at commit.
IGNORE: the implementation ignores the value the user set for the object's version
ALLOW: the implementation allows and uses the value the user set for the object's version

This allows users to who know how their implementation behaves on user-modified version values to take advantage of such behavior.

All names proposed are up for discussion.