RFR: 8375588: Enhanced property metadata

[John Hendrikx]

On Fri, 19 Dec 2025 20:56:27 GMT, Michael Strauß <mstrauss at openjdk.org> wrote:

> Implementation of [enhanced property metadata](https://gist.github.com/mstr2/2fec0303fc440b8eaeb126befc76eb5c).
> 
> ### New API
> This PR includes the following API additions:
> 
> 1. `ReadOnlyProperty.getDeclaringClass()` and its default implementation.
> 2. The `javafx.beans.property.AttachedProperty` interface.
> 3. New constructors for all `Simple<*>Property` and `ReadOnly<*>Wrapper` classes, accepting the declaring class of the property.
> 
> The declaring class is stored in a new field in the `Simple<*>Property` classes. If a legacy constructor is used that doesn't specify the declaring class, the `ReadOnlyProperty.getDeclaringClass()` default implementation is called the first time the `Simple<*>Property.getDeclaringClass()` method is called, and its result is stored for future retrieval.
> 
> ### Testing
> For testing, this PR also includes the `test.util.property.PropertyMetadataVerifier` tool. It systematically tests all public and protected properties of a class, and ensures conformance to the following rules:
> * `ReadOnlyProperty.getBean()` returns the object instance of the enclosing class, or the target object instance if the property is an attached property.
> *  `ReadOnlyProperty.getName()` returns the name of the property, which must correspond to the name of the property getter (excluding the word "Property").
> * `ReadOnlyProperty.getDeclaringClass()` returns the enclosing class of the property getter.
> * The declaring class of a `Simple<*>Property` or `ReadOnly<*>Wrapper` must be specified in the constructor, not resolved at runtime.
> * `getBean()`, `getName()`, and `getDeclaringClass()` must not be overridden in subclasses of `Simple<*>Property` or `ReadOnly<*>Wrapper`.
> * An instance property does not implement `AttachedProperty`.
> * An instance property has a parameterless property getter.
> * An attached property implements `AttachedProperty`.
> * An attached property has a static single-argument property getter that accepts the target object.
> * `AttachedProperty.getTargetClass()` returns the class of the single parameter of the static property getter.
> * A property getter does not return an instance of `ReadOnly<*>Wrapper`, it returns the result of calling `ReadOnly<*>Wrapper.getReadOnlyProperty()`.
> 
> Many properties in existing JavaFX classes violate the `PropertyMetadataVerifier` rules in some way or shape. This PR won't address these issues, this will be done in a future cleanup PR.

Let me say that I'd really like a mechanism such as this to be part of FX, but I do have some questions:

I think the `getDeclaringClass` on `ReadOnlyProperty` is okayish; however, I'd probably never take the time to override this method with a proper value, mostly because this requires creating a subclass to be efficient.  I know that within JavaFX, creating a subclass for each and every property (resulting in 1000's of subclasses) is "the standard", but for my own use, I never do this as it is just too much boilerplate.

I do however have a bit of problem with `isAttached`; what does this have to do with properties in general?  The description doesn't clarify what it means really, or what it even means outside the very specific case where HBox can "donate" properties to its children.

So to me, the attached part feels out of place for a low-level property API, unless there are compelling reasons and other use cases we'd envision outside of having CSS stylable child properties.  If not, I don't see why we shouldn't make this a method on `Stylable` or something more Node/CSS specific like in this PR: #1714

-------------

PR Comment: https://git.openjdk.org/jfx/pull/2015#issuecomment-3678804780