Improve Javadoc of ConfigurableFilePermissions.html#unix(int)

[sdavids]

Expected Behavior

Prevent misuse of API.

It is easy to think that unix(755) is rwxr-xr-x.

---

https://docs.gradle.org/current/javadoc/org/gradle/api/file/ConfigurableFilePermissions.html#unix(int)

Sets Unix style numeric permissions. See unix(String) for details.

https://docs.gradle.org/current/javadoc/org/gradle/api/file/ConfigurableFilePermissions.html#unix(java.lang.String)

The NUMERIC notation consist of 3 digits having values from 0 to 7. 1st digit represents the OWNER, 2nd represents the GROUP while the 3rd represents OTHER users.

Examples:

Numeric	Symbolic	Meaning
000	---------	no permissions
700	rwx------	read, write & execute only for owner

The description and the table suggest using a 3-digit number.

Current Behavior

gradle/platforms/core-configuration/file-collections/src/main/java/org/gradle/api/internal/file/DefaultConfigurableFilePermissions.java

Lines 96 to 100 in 035834c

	public void unix(int unixNumeric) {
	user.unix(getUserPartOf(unixNumeric));
	group.unix(getGroupPartOf(unixNumeric));
	other.unix(getOtherPartOf(unixNumeric));
	}

gradle/platforms/core-configuration/file-collections/src/main/java/org/gradle/api/internal/file/AbstractFilePermissions.java

Lines 32 to 35 in 035834c

	protected static int getUserPartOf(int unixNumeric) {
	return (unixNumeric & 0_700) >> 6;
	}

gradle/platforms/core-configuration/file-collections/src/main/java/org/gradle/api/internal/file/DefaultConfigurableUserClassFilePermissions.java

Lines 38 to 42 in 035834c

	public void unix(int unixNumeric) {
	setRead(isRead(unixNumeric));
	setWrite(isWrite(unixNumeric));
	setExecute(isExecute(unixNumeric));
	}

gradle/platforms/core-configuration/file-collections/src/main/java/org/gradle/api/internal/file/AbstractUserClassFilePermissions.java

Lines 33 to 35 in 035834c

	protected static boolean isRead(int unixNumeric) {
	return (unixNumeric & 4) >> 2 == 1;
	}

jshell --feedback=silent - <<< 'System.out.println((((755 & 0_700) >> 6) & 4) >> 2 == 1)'
false
 ~ % jshell --feedback=silent - <<< 'System.out.println((((0755 & 0_700) >> 6) & 4) >> 2 == 1)'
true

Context

https://docs.gradle.org/current/userguide/working_with_files.html#sec:setting_file_permissions

file: read & write for owner, read for group, read for other (0644, rw-r—​r--)

directory: read, write & execute for owner, read & execute for group, read & execute for other (0755, rwxr-xr-x)

https://docs.gradle.org/current/javadoc/org/gradle/api/file/FilePermissions.html

FILE: read & write for OWNER, read for GROUP, read for OTHER (0644, rw-r--r--)
DIRECTORY: read, write & execute for OWNER, read & execute for GROUP, read & execute for OTHER (0755, rwxr-xr-x)

Both are OK but could be improved with a WARNING that if using a number it should be in octal format.

---

unix(755) // not what one expects

unix(0755)
unix("755")
unix("rwxr-xr-x")

[sdavids]

https://kotlinlang.org/docs/numbers.html#literal-constants-for-numbers

Octal literals are not supported in Kotlin.

With the Gradle Kotlin-DSL unix(int) is basically useless and/or always leads to not what one expects.

[sdavids]

Maybe deprecate unix(int)?

[ljacomet]

This issue needs a decision from the team responsible for that area. They have been informed. Response time may vary.

---

At the minimum, the introduced unix(int) should have javadoc calling out this behaviour.

But we should consider if that method is really needed.

[github-actions]

@jbartok This issue was closed as completed and looks release-note worthy, but no PR with release-notes update has been found.
Please, do one of the following:

1. Attach a PR with the release notes update to this issue.
2. Add the has:release-notes-decision label to the issue if it's not release-note-worthy or it was fixed in an old release and close the issue.
3. Close issue as "not planned".

[github-actions]

@jbartok This issue was closed as completed and looks release-note worthy, but no PR with release-notes update has been found.
Please, do one of the following:

1. Attach a PR with the release notes update to this issue.
2. Add the has:release-notes-decision label to the issue if it's not release-note-worthy or it was fixed in an old release and close the issue.
3. Close issue as "not planned".

[jbartok]

The change is not release notes worthy (in my opinion).

[jbartok]

A couple of comments about the PR based on which this issue has been closed.

First of all, the problem/concern is not entirely realistic. Anybody who has to deal with UNIX style file permissions should be aware, to some extent at least, of the fact that the int value only makes sense in octal. So we have decided not to completely remove the method.

But, there is indeed some room for improvement, and that's what we did:

• we added validation which should catch many of the completely nonsensical inputs, that can be accidentally used
• we improved the JavaDoc to make the meaning of the values even clearer