UNOMI-955: Fix CI Javadoc failures and a dead shutdown crash-recovery path

[sergehuber]

Summary for non-technical readers

This change fixes two things that were making our automated tests unreliable on busy build servers, and fixes a documentation build error that was breaking our nightly publish job.

• Flaky tests: some automated tests were timing out on slower/busier test machines even though nothing was actually broken — they just needed a bit more patience. We gave them more time and more retry attempts.
• A real bug we found while fixing the above: when the scheduler shuts down, it's supposed to mark any in-progress task as "crashed" so it can be safely restarted later. We discovered this safety mechanism was silently failing to actually save its work, which could leave the system in an inconsistent state after a restart. This is now fixed and covered by new automated tests.
• Broken documentation builds: 24 files in one part of the codebase had malformed comments that broke our documentation generator. These are now cleaned up, and we added a --javadoc option to our build script so developers can catch this kind of error on their own machine before pushing, instead of finding out from a failed CI job.

Linked ticket

UNOMI-955 — Fix recurring CI failures and add local Javadoc validation to build script

Ticket scope:

1. Flaky tests due to timeouts calibrated for fast local environments rather than busy CI machines (scheduler and GraphQL test suites).
2. Cascading test failures: when the scheduler service stops, it leaves tasks in a RUNNING state, corrupting shared storage and breaking subsequent tests (ProfileServiceImplTest, SegmentServiceImplTest, RulesServiceImplTest).
3. Javadoc build errors: 24 files in the router extension contain stray </p> closing tags in their Javadoc comments, breaking the nightly Javadoc publish job.
4. No local validation: the build script lacked a Javadoc validation option, so developers couldn't catch doclint errors before pushing.

What changed

• Rewrote Javadoc across api, services-common, persistence-spi, and the router extensions so mvn javadoc:javadoc runs clean (no doclint errors), removing the malformed </p> tags called out in the ticket.
• Added a --javadoc flag to build.sh (also implied by --ci) that runs javadoc:javadoc and fails the build on doclint errors, so this class of failure is now catchable locally.
• Fixed a real bug found during review: SchedulerServiceImpl's shutdown sequence was meant to mark any task still RUNNING as CRASHED so it can be safely rescheduled, but it queried/saved tasks through wrapper methods (getAllTasks() / saveTask()) that silently no-op once the shutdown flag is set — so the crash-marking never actually persisted. Reworked it to go through the persistence provider directly.
• Added two new unit tests in SchedulerServiceImplTest that reproduce the bug against the old code (both fail with expected: <CRASHED> but was: <RUNNING>) and pass against the fix.
• Increased SchedulerServiceImplTest.TEST_TIMEOUT from 5s to 15s, and replaced a hardcoded retry count of 30 in GraphQLListIT with DEFAULT_TRYING_TRIES * 3, to give both suites more margin on loaded CI runners.

Test plan

• mvn javadoc:javadoc -DskipTests on api, services, services-common, persistence-spi, extensions/router/router-api, extensions/router/router-core — no doclint errors
• mvn -pl services test -Dtest=SchedulerServiceImplTest — 33/33 passing, including the two new regression tests
• Verified the two new tests fail against the pre-fix code (confirms they actually catch the bug) and pass against the fix
• mvn -pl itests -P integration-tests test-compile — GraphQLListIT change compiles

[Copilot]

Pull request overview

This PR improves CI reliability and documentation build stability by (1) increasing test resiliency on loaded CI runners, (2) fixing scheduler shutdown crash-recovery persistence so RUNNING tasks don’t poison subsequent runs, and (3) cleaning up Javadoc/doclint issues and adding a build-script option to validate Javadocs locally.

Changes:

• Fix SchedulerServiceImpl.preDestroy() to persistently mark RUNNING tasks as CRASHED during shutdown, and add regression tests.
• Reduce CI flakiness by increasing scheduler test timeouts and increasing GraphQL list IT retry attempts.
• Clean up malformed/invalid Javadoc across multiple modules and add --javadoc (and related logging flags) to build.sh.

Reviewed changes

Copilot reviewed 55 out of 56 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
services/src/main/java/org/apache/unomi/services/impl/scheduler/SchedulerServiceImpl.java	Adds shutdown-time CRASHED marking for RUNNING tasks.
services/src/test/java/org/apache/unomi/services/impl/scheduler/SchedulerServiceImplTest.java	Increases timeout and adds shutdown crash-marking regression tests.
itests/src/test/java/org/apache/unomi/itests/graphql/GraphQLListIT.java	Increases retry budget for async rule-engine processing on CI.
build.sh	Adds --javadoc validation and log-file output options; enables Javadoc in --ci.
services-common/src/main/java/org/apache/unomi/services/common/service/AbstractContextAwareService.java	Javadoc cleanup/clarification for tenant-context services.
services-common/src/main/java/org/apache/unomi/services/common/security/KarafSecurityService.java	Adds/cleans Javadoc for security service behavior.
services-common/src/main/java/org/apache/unomi/services/common/security/ExecutionContextManagerImpl.java	Adds/cleans Javadoc for thread-local execution context handling.
services-common/src/main/java/org/apache/unomi/services/common/security/AuditServiceImpl.java	Adds/cleans Javadoc for audit/persistence behavior.
services-common/src/main/java/org/apache/unomi/services/common/cache/AbstractMultiTypeCachingService.java	Javadoc cleanup for cache lifecycle and tenant/system inheritance behavior.
persistence-spi/src/main/java/org/apache/unomi/persistence/spi/conditions/PastEventConditionPersistenceQueryBuilder.java	Removes invalid/fragile Javadoc reference.
persistence-spi/src/main/java/org/apache/unomi/persistence/spi/conditions/evaluator/ConditionEvaluatorDispatcher.java	Removes invalid/fragile Javadoc reference.
persistence-spi/src/main/java/org/apache/unomi/persistence/spi/conditions/ConditionContextHelper.java	Fixes malformed Javadoc and clarifies overload behavior.
extensions/router/router-core/src/main/java/org/apache/unomi/router/core/strategy/StringLinesAggregationStrategy.java	Fixes malformed Javadoc (</p>).
extensions/router/router-core/src/main/java/org/apache/unomi/router/core/strategy/ArrayListAggregationStrategy.java	Fixes malformed Javadoc (</p>).
extensions/router/router-core/src/main/java/org/apache/unomi/router/core/route/RouterAbstractRouteBuilder.java	Fixes malformed Javadoc (</p>).
extensions/router/router-core/src/main/java/org/apache/unomi/router/core/route/ProfileImportToUnomiRouteBuilder.java	Fixes malformed Javadoc (</p>).
extensions/router/router-core/src/main/java/org/apache/unomi/router/core/route/ProfileImportOneShotRouteBuilder.java	Fixes malformed Javadoc (</p>).
extensions/router/router-core/src/main/java/org/apache/unomi/router/core/route/ProfileImportFromSourceRouteBuilder.java	Fixes malformed Javadoc (</p>).
extensions/router/router-core/src/main/java/org/apache/unomi/router/core/route/ProfileExportProducerRouteBuilder.java	Fixes malformed Javadoc (</p>).
extensions/router/router-core/src/main/java/org/apache/unomi/router/core/route/ProfileExportCollectRouteBuilder.java	Fixes malformed Javadoc (</p>).
extensions/router/router-core/src/main/java/org/apache/unomi/router/core/processor/UnomiStorageProcessor.java	Fixes malformed Javadoc (</p>).
extensions/router/router-core/src/main/java/org/apache/unomi/router/core/processor/LineSplitProcessor.java	Fixes malformed Javadoc (</p>).
extensions/router/router-core/src/main/java/org/apache/unomi/router/core/processor/LineSplitFailureHandler.java	Fixes malformed Javadoc (</p>).
extensions/router/router-core/src/main/java/org/apache/unomi/router/core/processor/LineBuildProcessor.java	Fixes malformed Javadoc (</p>).
extensions/router/router-core/src/main/java/org/apache/unomi/router/core/processor/ImportRouteCompletionProcessor.java	Fixes malformed Javadoc (</p>).
extensions/router/router-core/src/main/java/org/apache/unomi/router/core/processor/ImportConfigByFileNameProcessor.java	Fixes malformed Javadoc structure around <p> blocks.
extensions/router/router-core/src/main/java/org/apache/unomi/router/core/processor/ExportRouteCompletionProcessor.java	Fixes malformed Javadoc (</p>).
extensions/router/router-core/src/main/java/org/apache/unomi/router/core/context/RouterCamelContext.java	Fixes malformed Javadoc (</p>).
extensions/router/router-core/src/main/java/org/apache/unomi/router/core/bean/CollectProfileBean.java	Fixes malformed Javadoc (</p>).
extensions/router/router-api/src/main/java/org/apache/unomi/router/api/services/ProfileImportService.java	Fixes malformed Javadoc (</p>).
extensions/router/router-api/src/main/java/org/apache/unomi/router/api/services/ProfileExportService.java	Fixes malformed Javadoc (</p>).
extensions/router/router-api/src/main/java/org/apache/unomi/router/api/services/ImportExportConfigurationService.java	Fixes malformed Javadoc (</p>).
extensions/router/router-api/src/main/java/org/apache/unomi/router/api/ProfileToImport.java	Fixes malformed Javadoc (</p>).
extensions/router/router-api/src/main/java/org/apache/unomi/router/api/IRouterCamelContext.java	Fixes malformed Javadoc (</p>).
extensions/router/router-api/src/main/java/org/apache/unomi/router/api/ImportExportConfiguration.java	Fixes malformed Javadoc (</p>).
extensions/router/router-api/src/main/java/org/apache/unomi/router/api/exceptions/BadProfileDataFormatException.java	Fixes malformed Javadoc (</p>).
api/src/main/java/org/apache/unomi/api/utils/ConditionBuilder.java	Adds missing field/class Javadoc to satisfy doclint.
api/src/main/java/org/apache/unomi/api/tenants/security/TenantSecurityService.java	Removes invalid @throws Javadoc entry.
api/src/main/java/org/apache/unomi/api/tasks/ScheduledTask.java	Javadoc cleanup and clarification of scheduling/task model fields.
api/src/main/java/org/apache/unomi/api/services/SchedulerService.java	Escapes <= in Javadoc to satisfy doclint.
api/src/main/java/org/apache/unomi/api/services/ProfileService.java	Adds missing @return Javadoc.
api/src/main/java/org/apache/unomi/api/services/ConfigSharingService.java	Expands/cleans Javadoc for cross-bundle config sharing and events.
api/src/main/java/org/apache/unomi/api/services/ConditionValidationService.java	Expands/cleans Javadoc for validation behavior and error models.
api/src/main/java/org/apache/unomi/api/services/cache/CacheableTypeConfig.java	Adds Javadoc for TriConsumer.accept.
api/src/main/java/org/apache/unomi/api/query/Aggregate.java	Expands/cleans Javadoc for aggregation configuration.
api/src/main/java/org/apache/unomi/api/Item.java	Adds missing setter/getter Javadoc to satisfy doclint.
api/src/main/java/org/apache/unomi/api/exceptions/BadSegmentConditionException.java	Adds constructor Javadoc.
api/src/main/java/org/apache/unomi/api/CustomItem.java	Adds getter/setter Javadoc.
api/src/main/java/org/apache/unomi/api/ContextResponse.java	Adds Javadoc for getters/setters and deprecated methods.
api/src/main/java/org/apache/unomi/api/ContextRequest.java	Adds Javadoc for getters/setters.
api/src/main/java/org/apache/unomi/api/ConsentStatus.java	Adds enum value comments.
api/src/main/java/org/apache/unomi/api/conditions/ConditionValidation.java	Adds enum and accessor Javadoc.
api/src/main/java/org/apache/unomi/api/conditions/ConditionType.java	Adds item-type constant Javadoc.
api/src/main/java/org/apache/unomi/api/ClusterNode.java	Adds constant comment.
api/src/main/java/org/apache/unomi/api/actions/ActionType.java	Adds item-type constant Javadoc.
.gitignore	Ignores local venvs and generated Javadoc artifacts.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.