API REVIEW REQUEST: Public API for Backgrounds and Borders on Region

[Richard Bair]

Hi,

I have been working on some API for Java 8, which would expose as public API what has been private since we released JavaFX 2.0 (with modification). There has been @treatasprivate API on Region since 2.0 and this has to be removed & replaced. One reason is that as part of the Java 8 release requirements we're supposed to provide all the API our Controls use in their implementation as public API so that any 3rd party Control can be written using all public API (ie: all our Controls need to rely on public API instead of private internal hacks). Second, as we move towards proposing a JSR, we're obviously going to have to remove & replace all the impl_ @treatasprivate details with public or private API since the impl_ methods will never make it through a JSR into the standard.

As such, I have filed: http://javafx-jira.kenai.com/browse/RT-24506. I have attached to the issue the new API / implementations.

As you can see, there are a fair number of new classes! They are all immutable, meaning that they can be cached / reused among multiple instances. So for example, you can reuse the same Background or Border among multiple Regions. This is obviously a good thing when it comes to performance, because we can reduce the number of Background / Border instances in the system at any one time, since nearly every control is going to reuse one that already exists. On the other hand, the downside to this is that when animating between two styles (unless you do a cross fade animation), you would have to create lots of intermediate objects.

Having immutable objects also allows for some very good performance optimizations around caching. For example, while picking, we presently have to recompute the insets / outsets of all borders and backgrounds to determine whether the region is picked or not (if pickOnBounds is false). Now however, we can cache the answer once on the Background and it is a very fast operation to determine whether we picked or not.

On the rendering side, we can maintain a simple cache and use the Background as the key. Instead of rendering 5 backgrounds every time, we can render them once to a small image and use 9-patch rendering to scale the image and resize it and such.

If they were instead mutable objects, none of those techniques would be possible AND every region that used a Background would have to register listeners (or vice-versa) so that when the Background (or one of its properties deep inside it) changed, the Region could be marked invalid and re-drawn. Mutability would be a major issue in this case.

Please do have a look. There are a LOT of classes here, but if you have these classes in one hand and the CSS 3 spec in the other, hopefully you will see how we map the CSS 3 spec (and our existing CSS Reference for JavaFX) onto these classes and have provided for all of the (many, many, many) switches and twiddles that the spec allows for.

Thanks
Richard