8313651: Add 'final' keyword to public property methods in controls #1213

andy-goryachev-oracle · 2023-08-17T23:07:14Z

In the Control hierarchy, all property accessor methods must be declared final.

Added a test to check for missing final keyword and added the said keyword where required.

Progress

Change must not contain extraneous whitespace
Commit message must refer to an issue
Change requires CSR request JDK-8314581 to be approved
Change must be properly reviewed (2 reviews required, with at least 1 Reviewer, 1 Author)

Issues

JDK-8313651: Add 'final' keyword to public property methods in controls (Bug - P3)
JDK-8314581: Add 'final' keyword to public property methods in controls (CSR)

Reviewers

John Hendrikx (@hjohn - Committer)
Nir Lisker (@nlisker - Reviewer)
Kevin Rushforth (@kevinrushforth - Reviewer)

Reviewing

Using git

Checkout this PR locally:
$ git fetch https://git.openjdk.org/jfx.git pull/1213/head:pull/1213
$ git checkout pull/1213

Update a local copy of the PR:
$ git checkout pull/1213
$ git pull https://git.openjdk.org/jfx.git pull/1213/head

Using Skara CLI tools

Checkout this PR locally:
$ git pr checkout 1213

View PR using the GUI difftool:
$ git pr show -t 1213

Using diff file

Download this PR as a diff file:
https://git.openjdk.org/jfx/pull/1213.diff

Webrev

Link to Webrev Comment

bridgekeeper · 2023-08-17T23:07:52Z

👋 Welcome back angorya! A progress list of the required criteria for merging this PR into master will be added to the body of your pull request. There are additional pull request commands available for use with this pull request.

andy-goryachev-oracle · 2023-08-17T23:30:31Z

/csr

openjdk · 2023-08-17T23:31:31Z

@andy-goryachev-oracle has indicated that a compatibility and specification (CSR) request is needed for this pull request.

@andy-goryachev-oracle please create a CSR request for issue JDK-8313651 with the correct fix version. This pull request cannot be integrated until the CSR request is approved.

mlbridge · 2023-08-18T21:46:45Z

Webrevs

hjohn · 2023-08-18T22:04:11Z

modules/javafx.controls/src/test/java/test/javafx/scene/control/ControlPropertiesTest.java

+        sb.append(prefix);
+        for (int i = 0; i < name.length(); i++) {
+            char c = name.charAt(i);
+            if (i == 0) {
+                sb.append(Character.toUpperCase(c));
+            } else {
+                sb.append(c);
+            }
+        }


Suggested change

sb.append(prefix);

for (int i = 0; i < name.length(); i++) {

char c = name.charAt(i);

if (i == 0) {

sb.append(Character.toUpperCase(c));

} else {

sb.append(c);

}

}

sb.append(prefix);

sb.append(Character.toUpperCase(name.charAt(0)));

sb.append(name, 1, name.length);

good idea, thanks!

kevinrushforth · 2023-08-18T22:32:58Z

At first glance this looks good, but I'll need time to get back to it. And thanks for adding a test.

kevinrushforth · 2023-08-18T22:33:04Z

/reviewers 2

openjdk · 2023-08-18T22:33:37Z

@kevinrushforth
The total number of required reviews for this PR (including the jcheck configuration and the last /reviewers command) is now set to 2 (with at least 1 Reviewer, 1 Author).

andy-goryachev-oracle · 2023-08-18T22:36:49Z

And thanks for adding a test.

I feel the test can be improved by collecting the classes automatically, so as to catch possible issues when new controls are added (it'll be a full classpath scan though). While the scan should be limited to Controls, I wonder if other classes can benefit from enforcing the 'final' constraint?

kevinrushforth · 2023-08-18T22:53:42Z

Um, "classpath"? JavaFX is a collection of modules that are found on the module path. In any case, this seems better done as follow-up issue, if you want to file one.

Btw, having an automatic scan of "everything" seems like overkill, and isn't really desirable, so if you do want to go down this route, I'd keep it simple. Since any non-exported package (i.e., any pacakge that isn't under javafx.**) will already need to be explicitly listed in the test/addExports file, and since we so very rarely add a new package, you might consider having a hard coded List of packages that you enumerate looking for all classes in each package for ones with properties.

andy-goryachev-oracle · 2023-08-18T23:04:13Z

Um, "classpath"?

The problem I was referring to is how to enumerate all descendants of Control in javafx.* hierarchy, and I don't have a good solution. So, no change in the unit test is being planned, and all newly developed controls will have to be added manually.

nlisker · 2023-08-20T06:10:37Z

modules/javafx.controls/src/test/java/test/javafx/scene/control/ControlPropertiesTest.java

+import org.junit.Assert;
+import org.junit.Test;


These are JUnit 4, we should use 5 for new tests.

nlisker · 2023-08-20T06:11:05Z

modules/javafx.controls/src/test/java/test/javafx/scene/control/ControlPropertiesTest.java

+public class ControlPropertiesTest {
+    private static final boolean FAIL_FAST = true;


We use an empty line after the class declaration.

nlisker · 2023-08-20T06:16:06Z

modules/javafx.controls/src/test/java/test/javafx/scene/control/ControlPropertiesTest.java

+
+    // or perhaps collect all classes in a package as described here:
+    // https://stackoverflow.com/questions/28678026/how-can-i-get-all-class-files-in-a-specific-package-in-java
+    private Class[] allControlClasses() {
+        return new Class[] {


I was also thinking that these should be generated by the contents of the package. When I looked at javafx.scene.control I saw classes that weren't controls, but were used by them, so they would need to be removed. So it's a question of whitelist vs. blacklist.

In any case, I'm not sure why you're using an array here. Set.of seems more suitable and will also check for duplicate entries.

Respectfully disagree - these classes (in javafx.scene.control.cell) are public and in the Control hierarchy, so are subject of the 'final' limitation.

There are no duplicate classes.

The bigger problem is (my) inability to extract the list/set/array of classes automatically.

these classes (in javafx.scene.control.cell) are public and in the Control hierarchy, so are subject of the 'final' limitation.

I'm confused. Which classes should appear in this list exactly (what are the rules to determine that)?

Which classes should appear in this list exactly

subclasses of javafx.scene.control.Control

Ah, this is not easy. I thought that we need the classes in the control package. At this point it might just be simpler to use the hardcoded class list you already made and "hope" that new classes are added. There won't be many of these I suspect.

nlisker · 2023-08-20T21:17:18Z

modules/javafx.controls/src/test/java/test/javafx/scene/control/ControlPropertiesTest.java

+    @Test
+    public void testMissingFinalMethods() {
+        for (Class c: allControlClasses()) {
+            check(c);
+        }
+    }
+
+    private void check(Class cls) {
+        Method[] methods = cls.getMethods();
+
+        HashMap<String, Method> h = new HashMap<>();
+        for (Method m: methods) {
+            h.put(m.getName(), m);
+        }
+
+        for (Method m: methods) {
+            String name = m.getName();
+            if (name.endsWith("Property")) {
+                int mod = m.getModifiers();
+                if (Modifier.isPublic(mod)) {
+                    if (FAIL_FAST) {
+                        Assert.assertTrue(err(m, "is not final"), Modifier.isFinal(mod));
+                    } else {
+                        if (!Modifier.isFinal(mod)) {
+                            System.err.println(err(m, "is not final"));
+                        }
+                    }
+                }
+
+                String propName = name.substring(0, name.length() - "Property".length());
+                check(h, propName, "get", 0);
+                check(h, propName, "set", 1);
+                check(h, propName, "is", 0);
+            }
+        }
+    }
+
+    private void check(HashMap<String, Method> map, String name, String prefix, int numArgs) {
+        StringBuilder sb = new StringBuilder(64);
+        sb.append(prefix);
+        sb.append(Character.toUpperCase(name.charAt(0)));
+        sb.append(name, 1, name.length());
+
+        String s = sb.toString();
+        Method m = map.get(s);
+        if (m != null) {
+            if (m.getParameterCount() == numArgs) {
+                int mod = m.getModifiers();
+                if (Modifier.isPublic(mod)) {
+                    if (FAIL_FAST) {
+                        Assert.assertTrue(err(m, "is not final"), Modifier.isFinal(mod));
+                    } else {
+                        if (!Modifier.isFinal(mod)) {
+                            System.err.println(err(m, "is not final"));
+                        }
+                    }
+                }
+            }
+        }
+    }
+
+    private String err(Method method, String message) {
+        return method + " " + message;
+    }


(This comment didn't appear in the review for some reason.)

I think that the code could be a bit more clean. I took a stab at it:

Set<Class<?>> CLASSES = Set.of(/*...*/); private void check(Class<?> cls) { Map<String, Method> methods = Stream.of(cls.getMethods()).collect(Collectors.toMap(Method::getName, m -> m)); // the loop is also fine for (var method : methods.values()) { String name = method.getName(); if (name.endsWith("Property")) { checkModifiers(method); String propName = name.substring(0, name.length() - "Property".length()); check(methods, propName, "get", 0); check(methods, propName, "set", 1); check(methods, propName, "is", 0); } } } private void check(Map<String, Method> methods, String name, String prefix, int numArgs) { String methodName = new StringJoiner("", prefix, name.substring(0, 1).toUpperCase() + name.substring(1)).toString(); Method m = methods.get(methodName); if (m != null && m.getParameterCount() == numArgs) { checkModifiers(m); } } private void checkModifiers(Method m) { int mod = m.getModifiers(); if (Modifier.isPublic(mod) && !Modifier.isFinal(mod)) { if (FAIL_FAST) { throw new AssertionError(errorMessage(m)); } else { System.err.println(errorMessage(m)); } } } private String errorMessage(Method method) { return method + "is not final"; }

Thank you for suggestions!

Frankly, I don't see much value in rewriting of this method. A more interesting problem is how to enumerate all descendants of the Control class using the package name, in such a way that will reliably work in an IDE, from a JAR, or in any test framework (jtreg or otherwise).

edit: about the test itself - I see little difference between the two version, but will gladly use your version if you feel strongly about it.

edit: about the test itself - I see little difference between the two version, but will gladly use your version if you feel strongly about it.

I don't, I just think it's more readable. Fine to leave as is. What I might strongly suggest is extracting the checkModifiers method that is used in 2 places in your version.

done, and also fixed a stupid mistake ... method names are not unique.
many thanks!

hjohn · 2023-08-22T05:51:32Z

modules/javafx.controls/src/test/java/test/javafx/scene/control/ControlPropertiesTest.java

 public class ControlPropertiesTest {
-    private static final boolean FAIL_FAST = true;

+    private static final boolean FAIL_FAST = !true;


Did you intend to commit this? It was true before which seems good for tests, otherwise I'd really suggest using false here.

sorry, committed by accident. thanks for noticing!

nlisker

Looks good. Gave a couple of minor optional suggestions.

As to the topic of class finding, I think it's fine to use a manual list, at least for now. The complexity of automatically detecting the classes might not be worth the hassle. Leaving it up to you.

nlisker · 2023-08-22T09:13:08Z

modules/javafx.controls/src/test/java/test/javafx/scene/control/ControlPropertiesTest.java

+     */
+    @Test
+    public void testMissingFinalMethods() {
+        for (Class c: allControlClasses()) {


I think we use a space before :. Don't know if it's being enforced. If you change it there are 2 more places.

Adding superfluous spaces increases our carbon footprint ;-)
Modified the formatter to increase the footprint.

The space before : is still missing here.

nlisker · 2023-08-22T09:13:42Z

modules/javafx.controls/src/test/java/test/javafx/scene/control/ControlPropertiesTest.java

+    }
+
+    /**
+     * Tests for missing final keyword in Control properties and their accessors.


Technically, we're looking at mutators too, not just accessors.

nlisker · 2023-08-22T09:14:07Z

modules/javafx.controls/src/test/java/test/javafx/scene/control/ControlPropertiesTest.java

+import com.sun.javafx.scene.control.skin.FXVK;
+
+/**
+ * Tests contract for properties and their accessors in the Control type hierarchy.


Mutators too?

kevinrushforth

The fix looks good. So does the test with a couple comments. I also noted a couple potential follow-up items.

kevinrushforth · 2023-09-07T22:31:14Z

modules/javafx.controls/src/test/java/test/javafx/scene/control/ControlPropertiesTest.java

+ * in the Control type hierarchy.
+ *
+ * Currently uses a list of classes, so any new Controls must be added manually.
+ * Perhaps the test should scan classpath and find all the Controls automagically.


Minor: "classpath" --> "modulepath"

More interesting question: Should we do this in other modules (e.g., javafx.graphics), too? If so, that would be for a follow-up issue.

kevinrushforth · 2023-09-07T22:35:13Z

modules/javafx.controls/src/test/java/test/javafx/scene/control/ControlPropertiesTest.java

+
+    // list all descendants of Control class.
+    // or perhaps collect all classes in a package as described here:
+    // https://stackoverflow.com/questions/28678026/how-can-i-get-all-class-files-in-a-specific-package-in-java


Please remove the reference to stackoverflow.

kevinrushforth · 2023-09-07T22:38:15Z

modules/javafx.controls/src/test/java/test/javafx/scene/control/ControlPropertiesTest.java

+     */
+    @Test
+    public void testMissingFinalMethods() {
+        for (Class c: allControlClasses()) {


The space before : is still missing here.

kevinrushforth · 2023-09-07T22:42:57Z

modules/javafx.controls/src/test/java/test/javafx/scene/control/ControlPropertiesTest.java

+
+    private void checkModifiers(Method m) {
+        int mod = m.getModifiers();
+        if (Modifier.isPublic(mod) && !Modifier.isFinal(mod)) {


Should we also check protected methods? If so, that would be something for a follow-up issue.

easy enough to add, and makes sense.

kevinrushforth · 2023-09-08T13:02:31Z

modules/javafx.controls/src/test/java/test/javafx/scene/control/ControlPropertiesTest.java

+    }
+
+    private void check(Class cls) {
+        Method[] methods = cls.getMethods();


This will only return public methods. Since you modified checkModifiers to check protected methods, you will need to use getDeclaredMethods instead. This will return protected (and package scope) methods as well as public methods. It won't return any method in a superclass, but since the set of classes you are checking includes intermediate classes (such as ButtonBase and Labeled), you will still get the coverage (and without redundantly checking the same method in those classes multiple times).

Right, what was I thinking??
And we also have Region.setWidth() which is protected and not final by design. Reverting the last change.

kevinrushforth

Looks good.

kevinrushforth · 2023-09-08T17:20:08Z

@nlisker @hjohn Can you re-review?

nlisker

Looks good. Added some minor comments.

nlisker · 2023-09-08T18:13:45Z

modules/javafx.controls/src/test/java/test/javafx/scene/control/ControlPropertiesTest.java

+    private Set<Class> allControlClasses() {
+        return Set.of(


Not that it matters much since the method is called once, but why is there a need for a method that returns the same constant set? The set can just be a constant: private final Set<Class<?>> = Set.of(...);

will keep as a method, if we ever get to extracting classes at run time.

nlisker · 2023-09-08T18:15:43Z

modules/javafx.controls/src/test/java/test/javafx/scene/control/ControlPropertiesTest.java

+            } else {
+                System.err.println(msg);
+            }


No need for an else clause since throw will exit the scope of the method if it's reached.

personal style.

nlisker · 2023-09-08T18:17:16Z

modules/javafx.controls/src/test/java/test/javafx/scene/control/ControlPropertiesTest.java

+    private static final boolean FAIL_FAST = true;
+
+    // list all current descendants of Control class.
+    private Set<Class> allControlClasses() {


Please use Class<?> instead of raw types. In 2 other places below as well.

modules/javafx.controls/src/test/java/test/javafx/scene/control/ControlPropertiesTest.java

openjdk · 2023-09-08T21:36:27Z

@andy-goryachev-oracle This change now passes all automated pre-integration checks.

ℹ️ This project also has non-automated pre-integration requirements. Please see the file CONTRIBUTING.md for details.

After integration, the commit message for the final commit will be:

8313651: Add 'final' keyword to public property methods in controls

Reviewed-by: jhendrikx, nlisker, kcr

You can use pull request commands such as /summary, /contributor and /issue to adjust it as needed.

At the time when this comment was updated there had been 2 new commits pushed to the master branch:

eb7de72: 8315317: Add test for JDK-8262518
ed92171: 8315870: icu fails to compile with Visual Studio 2022 17.6.5

Please see this link for an up-to-date comparison between the source branch of this pull request and the master branch.
As there are no conflicts, your changes will automatically be rebased on top of these commits when integrating. If you prefer to avoid this automatic rebasing, please check the documentation for the /integrate command for further details.

➡️ To integrate this PR with the above commit message to the master branch, type /integrate in a new comment.

andy-goryachev-oracle · 2023-09-11T18:01:59Z

/integrate

openjdk · 2023-09-11T18:02:42Z

Going to push as commit 624fe86.
Since your change was applied there have been 3 commits pushed to the master branch:

325be56: 8310666: gradle validateSourceSets task not run when TEST_ONLY=true
eb7de72: 8315317: Add test for JDK-8262518
ed92171: 8315870: icu fails to compile with Visual Studio 2022 17.6.5

Your commit was automatically rebased without conflicts.

openjdk · 2023-09-11T18:02:51Z

@andy-goryachev-oracle Pushed as commit 624fe86.

💡 You may see a message that your pull request was closed with unmerged commits. This can be safely ignored.

andy-goryachev-oracle added 2 commits August 17, 2023 16:04

test

5f6edef

added final keyword

38c3b25

whitespace

24a8136

openjdk bot added the csr Need approved CSR to integrate pull request label Aug 17, 2023

andy-goryachev-oracle marked this pull request as ready for review August 18, 2023 21:40

openjdk bot added the rfr Ready for review label Aug 18, 2023

hjohn approved these changes Aug 18, 2023

View reviewed changes

review comments

c7808a9

andy-goryachev-oracle requested a review from hjohn August 18, 2023 22:22

hjohn approved these changes Aug 18, 2023

View reviewed changes

nlisker reviewed Aug 20, 2023

View reviewed changes

andy-goryachev-oracle added 3 commits August 21, 2023 07:55

Merge remote-tracking branch 'origin/master' into 8313651.final

52ef745

review comments

797285d

review comments

505c848

hjohn approved these changes Aug 22, 2023

View reviewed changes

nlisker approved these changes Aug 22, 2023

View reviewed changes

review comments

38a4ba5

kevinrushforth self-requested a review August 29, 2023 15:59

kevinrushforth reviewed Sep 7, 2023

View reviewed changes

andy-goryachev-oracle added 2 commits September 7, 2023 16:26

review comments

98a84b0

Merge remote-tracking branch 'origin/master' into 8313651.final

76b1283

kevinrushforth reviewed Sep 8, 2023

View reviewed changes

only public

65aa089

kevinrushforth approved these changes Sep 8, 2023

View reviewed changes

nlisker reviewed Sep 8, 2023

View reviewed changes

review comments

0c5c304

nlisker approved these changes Sep 8, 2023

View reviewed changes

kevinrushforth approved these changes Sep 8, 2023

View reviewed changes

openjdk bot added ready Ready to be integrated and removed csr Need approved CSR to integrate pull request labels Sep 8, 2023

hjohn approved these changes Sep 9, 2023

View reviewed changes

openjdk bot added the integrated Pull request has been integrated label Sep 11, 2023

openjdk bot closed this Sep 11, 2023

openjdk bot removed ready Ready to be integrated rfr Ready for review labels Sep 11, 2023

andy-goryachev-oracle deleted the 8313651.final branch September 11, 2023 18:03

		public class ControlPropertiesTest {
		private static final boolean FAIL_FAST = true;

		import org.junit.Assert;
		import org.junit.Test;

8313651: Add 'final' keyword to public property methods in controls #1213

8313651: Add 'final' keyword to public property methods in controls #1213

Uh oh!

Conversation

andy-goryachev-oracle commented Aug 17, 2023 • edited by openjdk bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Progress

Issues

Reviewers

Reviewing

Webrev

Uh oh!

bridgekeeper bot commented Aug 17, 2023

Uh oh!

andy-goryachev-oracle commented Aug 17, 2023

Uh oh!

openjdk bot commented Aug 17, 2023

Uh oh!

mlbridge bot commented Aug 18, 2023 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Webrevs

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

kevinrushforth commented Aug 18, 2023

Uh oh!

kevinrushforth commented Aug 18, 2023

Uh oh!

openjdk bot commented Aug 18, 2023

Uh oh!

andy-goryachev-oracle commented Aug 18, 2023

Uh oh!

kevinrushforth commented Aug 18, 2023

Uh oh!

andy-goryachev-oracle commented Aug 18, 2023

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

andy-goryachev-oracle Aug 21, 2023 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

nlisker left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

kevinrushforth left a comment

andy-goryachev-oracle commented Aug 17, 2023 •

edited by openjdk bot

Loading

mlbridge bot commented Aug 18, 2023 •

edited

Loading

andy-goryachev-oracle Aug 21, 2023 •

edited

Loading

nlisker Sep 8, 2023 •

edited

Loading