A bit of javadoc for codegen

[aloubyansky]

Related to #31783

[ppalaga]

Thanks a lot, @aloubyansky. I asked for some more details inline.

[ppalaga]

Absolute or relative (to what?).
An example would be nice. Something like , e.g. {@code target/generated-sources/foo} for a CodeGenProvider having providerId {@code foo}` - I hope that's what it does?

[ppalaga]

Absolute or relative (to what?).
What is main build directory? target for Maven? Or target/classes?

[aloubyansky]

Absolute or relative (to what?).

It should be an absolute, however, I'm not sure we guarantee that. It'd be a path that can be used in a CodeGenProvider.trigger(CodeGenContext context) method as a working dir.

What is main build directory? target for Maven? Or target/classes?

target for Maven, ${project.build.directory}

[ppalaga]

Absolute or relative (to what?).

It should be an absolute, however, I'm not sure we guarantee that. It'd be a path that can be used in a CodeGenProvider.trigger(CodeGenContext context) method as a working dir.

Well, what I'd like to know here and for every other Path in this API is whether I need to resolve the path against some sort of a base dir before being able to read/write from/to the underlying file/dir. If I can do that, then it is de facto absolute for me and the JavaDoc could say something like

The returned path is either absolute or relatative to the current directory of the JVM so you can read/write to the underlying file or directory without further resolving it.

[aloubyansky]

Yes, that's a usable path like any other in this API. I think it'd be a common case for an API to return a File or a Path that is usable/consumable w/o further resolution. If it's not it has to be documented.

[ppalaga]

Absolute or relative (to what?).
An example would be nice, something like {@code src/main/foo} for a CodeGenProvider having inputDirectory {@code foo}

[ppalaga]

What does redirect IO mean here? Redirect System.[in|out|err]? Redirect where and how? In which situations do I need to care?

[ppalaga]

Does this return false for dev mode?

[aloubyansky]

Not necessarily. We do generate code for tests when launching dev mode to be able to run continuous testing.

[ppalaga]

OK, I see, thanks for explaining! Then the text is correct.

[ppalaga]

Absolute or relative (to what)?

[aloubyansky]

It's the caller that provides the value of the root.

[ppalaga]

For both ArchivePathTree and DirectoryPathTree you seem to be calling Files.walk(rootDir) right after creating PathTreeVisit so the value of rootDir must be de facto absolute. I guess the API users are nor supposed to add new implementations of PathVisit and they mostly interact with it via their custom PathVisitors that they pass to PathTree.walk(PathVisitor). So for the API users, PathVisit instances are supplied by the API and they deserve to know whether the paths returned by PathVisit methods are (de facto) absolute.

[aloubyansky]

you seem to be calling Files.walk(rootDir) right after creating PathTreeVisit so the value of rootDir must be de facto absolute

The rootDir does not have to be an absolute path for Files.walk(rootDir) to work though.

[aloubyansky]

Peter, based on my comment above, I wouldn't say it's "de facto absolute". It really depends on what the rootDir path is, which is provided by the caller.
Otherwise, from my perspective, this javadoc is pretty much in line with https://docs.oracle.com/en/java/javase/11/docs/api/java.base/java/nio/file/FileVisitor.html Or am I still missing something? Or you'd also have similar remarks for that the FileVisitor javadoc?

[ppalaga]

Peter, based on my comment above, I wouldn't say it's "de facto absolute". It really depends on what the rootDir path is, which is provided by the caller.

Sorry, "de facto absolute" is perhaps misleading. What I mean is "ready for IO operations" or simply "granted to exist". I admit it is rather trivial to document for getRoot() but it would be really nice to add a sentence to getPath() stating something like

The returned path is granted to exist in the underlying filesystem (unless it was deleted by a parallel process or thread) and therefore it can be used for I/O operations straight away without further resolving e.g. against getRoot().

[aloubyansky]

Added, thanks

[ppalaga]

Absolute or relative (to what)?

[aloubyansky]

It might depend on whether the root is absolute or relative. It will be a path that can be read during the visit.

[ppalaga]

It will be a path that can be read during the visit.

Exactly, that's a piece of super important info I'd like to find in JavaDoc!

[ppalaga]

Thanks @aloubyansky a0e8695 is is a great improvement! What is still open from my PoV:

• The absolute/relative path information
• Rephrase the redirect IO method

[quarkus-bot]

Failing Jobs - Building 268dbb7

Status	Name	Step	Failures	Logs	Raw logs
✔️	Gradle Tests - JDK 11
⌛	Gradle Tests - JDK 11 Windows	Build	Failures	Logs	Raw logs
✔️	JVM Tests - JDK 11
⌛	JVM Tests - JDK 17	Build	⚠️ Check →	Logs	Raw logs
✖	JVM Tests - JDK 17 Windows	Build	Failures	Logs	Raw logs
✔️	JVM Tests - JDK 19
✖	Maven Tests - JDK 11	Build	Failures	Logs	Raw logs
✖	Maven Tests - JDK 11 Windows	Build	Failures	Logs	Raw logs
⌛	Native Tests - Data6	Build	⚠️ Check →	Logs	Raw logs

Full information is available in the Build summary check run.

Failures

⚙️ Gradle Tests - JDK 11 Windows #

📦 integration-tests/gradle

✖ io.quarkus.gradle.devmode.QuarkusDevDependencyDevModeTest.main line 14 - More details - Source on GitHub

org.awaitility.core.ConditionTimeoutException: Condition with lambda expression in io.quarkus.test.devmode.util.DevModeTestUtils that uses java.util.function.Supplier, java.util.function.Supplierjava.util.concurrent.atomic.AtomicReference, java.util.concurrent.atomic.AtomicReferencejava.lang.String, java.lang.Stringboolean was not fulfilled within 1 minutes.
	at org.awaitility.core.ConditionAwaiter.await(ConditionAwaiter.java:167)
	at org.awaitility.core.CallableCondition.await(CallableCondition.java:78)

---

⚙️ JVM Tests - JDK 17 Windows #

- Failing: extensions/vertx/deployment 
! Skipped: extensions/agroal/deployment extensions/amazon-lambda-http/deployment extensions/amazon-lambda-rest/deployment and 362 more

📦 extensions/vertx/deployment

✖ io.quarkus.vertx.mdc.VertxMDCTest.mdc line 144 - More details - Source on GitHub

org.opentest4j.AssertionFailedError: expected: <10> but was: <0>
	at org.junit.jupiter.api.AssertionFailureBuilder.build(AssertionFailureBuilder.java:151)
	at org.junit.jupiter.api.AssertionFailureBuilder.buildAndThrow(AssertionFailureBuilder.java:132)

✖ io.quarkus.vertx.mdc.VertxMDCTest.mdcNonVertxThreadTest line 121 - More details - Source on GitHub

java.lang.AssertionError: 

Expected: a collection containing "Test MDC value ### Test 1"

---

⚙️ Maven Tests - JDK 11 #

- Failing: integration-tests/maven 

📦 integration-tests/maven

✖ io.quarkus.maven.it.DevMojoIT.testThatTheTestsAreReRunMultiModule - More details - Source on GitHub

org.awaitility.core.ConditionTimeoutException: Failed to wait for test run3 TestStatus{lastRun=2, running=3, testsRun=2, testsPassed=0, testsFailed=1, testsSkipped=0}
	at io.quarkus.maven.it.continuoustesting.ContinuousTestingMavenTestUtils.waitForNextCompletion(ContinuousTestingMavenTestUtils.java:74)
	at io.quarkus.maven.it.LaunchMojoTestBase.testThatTheTestsAreReRunMultiModule(LaunchMojoTestBase.java:63)

✖ io.quarkus.maven.it.DevMojoIT.testThatTheTestsAreReRunMultiModule - More details - Source on GitHub

org.awaitility.core.ConditionTimeoutException: Failed to wait for test run3 TestStatus{lastRun=2, running=3, testsRun=2, testsPassed=0, testsFailed=1, testsSkipped=0}
	at io.quarkus.maven.it.continuoustesting.ContinuousTestingMavenTestUtils.waitForNextCompletion(ContinuousTestingMavenTestUtils.java:74)
	at io.quarkus.maven.it.LaunchMojoTestBase.testThatTheTestsAreReRunMultiModule(LaunchMojoTestBase.java:63)

---

⚙️ Maven Tests - JDK 11 Windows #

- Failing: integration-tests/maven 

📦 integration-tests/maven

✖ io.quarkus.maven.it.DevMojoIT.testThatTheTestsAreReRunMultiModule - More details - Source on GitHub

org.awaitility.core.ConditionTimeoutException: Failed to wait for test run3 TestStatus{lastRun=2, running=3, testsRun=2, testsPassed=0, testsFailed=1, testsSkipped=0}
	at io.quarkus.maven.it.continuoustesting.ContinuousTestingMavenTestUtils.waitForNextCompletion(ContinuousTestingMavenTestUtils.java:74)
	at io.quarkus.maven.it.LaunchMojoTestBase.testThatTheTestsAreReRunMultiModule(LaunchMojoTestBase.java:63)

✖ io.quarkus.maven.it.DevMojoIT.testThatTheApplicationIsReloadedMultiModule line 611 - More details - Source on GitHub

org.awaitility.core.ConditionTimeoutException: Failed to wait for test run3 TestStatus{lastRun=2, running=3, testsRun=2, testsPassed=0, testsFailed=1, testsSkipped=0}
	at io.quarkus.maven.it.continuoustesting.ContinuousTestingMavenTestUtils.waitForNextCompletion(ContinuousTestingMavenTestUtils.java:74)
	at io.quarkus.maven.it.DevMojoIT.testThatTheApplicationIsReloadedMultiModule(DevMojoIT.java:611)

✖ io.quarkus.maven.it.DevMojoIT.testThatTheTestsAreReRunMultiModule - More details - Source on GitHub

org.awaitility.core.ConditionTimeoutException: Failed to wait for test run3 TestStatus{lastRun=2, running=3, testsRun=2, testsPassed=0, testsFailed=1, testsSkipped=0}
	at io.quarkus.maven.it.continuoustesting.ContinuousTestingMavenTestUtils.waitForNextCompletion(ContinuousTestingMavenTestUtils.java:74)
	at io.quarkus.maven.it.LaunchMojoTestBase.testThatTheTestsAreReRunMultiModule(LaunchMojoTestBase.java:63)

✖ io.quarkus.maven.it.DevMojoIT.testThatTheApplicationIsReloadedMultiModule line 611 - More details - Source on GitHub

org.awaitility.core.ConditionTimeoutException: Failed to wait for test run3 TestStatus{lastRun=2, running=3, testsRun=2, testsPassed=0, testsFailed=1, testsSkipped=0}
	at io.quarkus.maven.it.continuoustesting.ContinuousTestingMavenTestUtils.waitForNextCompletion(ContinuousTestingMavenTestUtils.java:74)
	at io.quarkus.maven.it.DevMojoIT.testThatTheApplicationIsReloadedMultiModule(DevMojoIT.java:611)

[ppalaga]

Thanks @aloubyansky !