80: Introduce an explicit Hub-managed JavaFX runtime service
This commit is contained in:
@@ -0,0 +1,80 @@
|
||||
# javafx-runtime-service Specification
|
||||
|
||||
## Purpose
|
||||
TBD - created by archiving change 80-introduce-javafx-runtime-service. Update Purpose after archive.
|
||||
## Requirements
|
||||
### Requirement: JavaFX runtime service separates use from lifecycle
|
||||
`com.r35157.service.javafx.JavaFxRuntimeService` SHALL be a public `NenjimComponent` interface exposing exactly `void runLater(@NotNull Runnable runnable)` and no initialization, shutdown, restart, status, configuration, window-management, event, or lifecycle operation. `com.r35157.service.javafx.impl.ref.JavaFxRuntimeServiceImpl` SHALL implement both that service and the canonical `NenjimProcess`, so one object supplies the ordinary service view and the Hub-owned process view without a separate manager or administration interface.
|
||||
|
||||
#### Scenario: Consumer receives only the service view
|
||||
- **WHEN** an ordinary JavaFX application receives a `JavaFxRuntimeService`
|
||||
- **THEN** it can submit non-null JavaFX work but cannot start, stop, restart, configure, inspect, or administer the runtime through that API
|
||||
|
||||
#### Scenario: One implementation supplies both views
|
||||
- **WHEN** one `JavaFxRuntimeServiceImpl` is registered once
|
||||
- **THEN** Registry lookup through `JavaFxRuntimeService` and `NenjimProcess` returns the identical object reference
|
||||
|
||||
### Requirement: JavaFX runtime startup is one-attempt and complete
|
||||
The implementation's `start()` SHALL be the only operation that calls `Platform.startup(...)`. It SHALL accept only the first attempt, configure `Platform.setImplicitExit(false)` on the JavaFX startup callback, wait for that callback to complete successfully, and open service availability only before returning successfully. Every repeated attempt SHALL fail with `IllegalStateException`, including after first-attempt failure or interruption. A synchronous or callback initialization failure SHALL propagate with a clear service-startup diagnostic, leave the service unavailable, and SHALL not be retried, recovered, restarted, rolled back, or silently accepted as an externally initialized toolkit.
|
||||
|
||||
#### Scenario: First startup succeeds
|
||||
- **WHEN** JavaFX startup invokes its callback and implicit exit is disabled successfully
|
||||
- **THEN** `start()` returns only after that callback completes and the service becomes available
|
||||
|
||||
#### Scenario: Startup callback has not completed
|
||||
- **WHEN** `Platform.startup(...)` has accepted initialization but its callback has not completed
|
||||
- **THEN** `start()` has not returned successfully and task submission remains unavailable
|
||||
|
||||
#### Scenario: Startup fails
|
||||
- **WHEN** toolkit initialization or callback configuration fails
|
||||
- **THEN** `start()` propagates a clear failure and the service remains unavailable without partial success
|
||||
|
||||
#### Scenario: Startup is repeated
|
||||
- **WHEN** `start()` is called after any earlier attempt began
|
||||
- **THEN** it fails with `IllegalStateException` without calling `Platform.startup(...)` again
|
||||
|
||||
#### Scenario: Last window closes
|
||||
- **WHEN** the last JavaFX window closes after successful service startup
|
||||
- **THEN** disabled implicit exit keeps the shared JavaFX runtime alive for later submitted work
|
||||
|
||||
### Requirement: JavaFX task submission is non-null gated and asynchronous
|
||||
`runLater(...)` SHALL reject null with `NullPointerException`. Before successful startup and after failed startup it SHALL reject every non-null task with `IllegalStateException` without initializing, starting, or retrying JavaFX and without executing the task. After successful startup it SHALL submit the exact task through `Platform.runLater(...)` and SHALL never execute it synchronously on the caller's thread. Acceptance SHALL make no guarantee that application UI work completes successfully, and exceptions raised by that work SHALL not change the completed runtime startup milestone.
|
||||
|
||||
#### Scenario: Null task is submitted
|
||||
- **WHEN** `runLater(null)` is called in any service state
|
||||
- **THEN** it fails with `NullPointerException` identifying the null task
|
||||
|
||||
#### Scenario: Task is submitted before successful startup
|
||||
- **WHEN** a caller submits a non-null task before `start()` succeeds or after its failure
|
||||
- **THEN** submission fails with `IllegalStateException` without any JavaFX initialization or synchronous task execution
|
||||
|
||||
#### Scenario: Task is accepted after startup
|
||||
- **WHEN** a non-null task is submitted after successful startup
|
||||
- **THEN** the service passes it to `Platform.runLater(...)` for asynchronous execution on the JavaFX Application Thread
|
||||
|
||||
#### Scenario: Application task fails
|
||||
- **WHEN** accepted UI work later throws on the JavaFX Application Thread
|
||||
- **THEN** that remains an application failure and does not convert the service's successful startup into a runtime startup failure
|
||||
|
||||
### Requirement: Modern JavaFX consumers require the shared service
|
||||
`EvelynMissionControlImpl`, `NenjimProcessManagerImpl`, `NenjimComposerImpl`, `NenjimTestToolImpl`, `SodaTaskManagerImpl`, and `SuwimoClientImpl` SHALL each require, reject null for, retain, and use a constructor-injected `JavaFxRuntimeService` for JavaFX Application Thread submission. No compatibility constructor, static fallback, direct `Platform.startup(...)`, lazy initialization helper, or competing initialization flag SHALL remain in the modern component graph. Direct ordinary JavaFX UI API use inside application code SHALL remain valid.
|
||||
|
||||
#### Scenario: Consumer dependency is null
|
||||
- **WHEN** any modern JavaFX implementation is constructed with a null runtime service
|
||||
- **THEN** construction fails with `NullPointerException`
|
||||
|
||||
#### Scenario: Consumer starts UI work
|
||||
- **WHEN** any modern JavaFX consumer requests window creation or JavaFX publication
|
||||
- **THEN** it submits through its retained service and neither initializes JavaFX nor falls back to static behavior
|
||||
|
||||
#### Scenario: Static initialization path is inspected
|
||||
- **WHEN** modern source is searched after migration
|
||||
- **THEN** `com.r35157.libs.javafx.JavaFxRuntime` is absent and only `JavaFxRuntimeServiceImpl.start()` calls `Platform.startup(...)`
|
||||
|
||||
### Requirement: Deferred JavaFX runtime features remain absent
|
||||
The JavaFX runtime service SHALL represent one JVM-wide toolkit and SHALL not implement multiple toolkits, headless emulation, toolkit replacement, shutdown, stop, restart, recovery, supervision, health monitoring, runtime status queries, window discovery or management, configuration, Context resolution, automatic dependency discovery/startup, lifecycle events, or subscriptions. This change SHALL not add `NenjimHub.conf` or configurable autorun.
|
||||
|
||||
#### Scenario: Runtime boundary is inspected
|
||||
- **WHEN** the delivered service, process implementation, Hub integration, and application constructors are examined
|
||||
- **THEN** only explicit one-time startup, asynchronous task submission, fixed Hub ordering, and dependency injection are present
|
||||
|
||||
@@ -186,7 +186,7 @@ The reference Registry construction boundary SHALL create one Registry object ex
|
||||
- **THEN** no component ID identifies the manager and no lookup returns it as a component or process
|
||||
|
||||
### Requirement: NenjimHub owns composition and runtime startup
|
||||
`NenjimHub` SHALL be the global runtime owner and SHALL expose `start() throws Exception` plus an immutable ordered snapshot of successfully started process IDs. It SHALL be neither a component nor a process and SHALL not register itself. Its only accepted startup attempt SHALL construct the Registry subsystem, start the Registry process first, register it as `nenjim.registry.service`, construct and register the Journal subsystem as `nenjim.journal.service`, start Journal second, and continue to the complete hardcoded business component set from issue #76 only after Journal startup succeeds. During application composition the Hub SHALL construct the Process Manager with itself and register it as `nenjim.process-manager.default`. The Hub SHALL resolve only the explicitly enabled IDs through `NenjimProcess`, start them in dependency-safe order with the Process Manager last, announce the existing online point, and preserve the existing blocking wait. Registration SHALL never imply startup, and the Registry and Journal managers SHALL remain distinct passive, unregistered handles retained privately by the Hub.
|
||||
`NenjimHub` SHALL be the global runtime owner and SHALL expose `start() throws Exception` plus an immutable ordered snapshot of successfully started process IDs. It SHALL be neither a component nor a process and SHALL not register itself. Its only accepted startup attempt SHALL construct the Registry subsystem, start the Registry process first, register it as `nenjim.registry.service`, construct and register the Journal subsystem as `nenjim.journal.service`, start Journal second, and continue to the complete hardcoded business component set from issue #76 only after Journal startup succeeds. During application composition the Hub SHALL construct exactly one `JavaFxRuntimeServiceImpl`, register it as `nenjim.javafx-runtime.service`, inject its service view into Mission Control and Process Manager, construct the Process Manager with itself, and register that manager as `nenjim.process-manager.default`. The Hub SHALL resolve only explicitly enabled IDs through `NenjimProcess`, start the JavaFX runtime service after enabled non-JavaFX business processes and before Mission Control and Process Manager, start Process Manager last, announce the existing online point, and preserve the existing blocking wait. Registration SHALL never imply startup, and the Registry and Journal managers SHALL remain distinct passive, unregistered handles retained privately by the Hub.
|
||||
|
||||
#### Scenario: Registry starts before graph construction
|
||||
- **WHEN** the Hub performs its first startup attempt
|
||||
@@ -204,17 +204,25 @@ The reference Registry construction boundary SHALL create one Registry object ex
|
||||
- **WHEN** the Journal registration has completed
|
||||
- **THEN** the same object is retrievable as both `JournalService` and `NenjimProcess` under `nenjim.journal.service`, while its manager is not registered
|
||||
|
||||
#### Scenario: JavaFX runtime is process-discoverable
|
||||
- **WHEN** Hub-owned application composition has completed
|
||||
- **THEN** one object is retrievable as both `JavaFxRuntimeService` and `NenjimProcess` under `nenjim.javafx-runtime.service`
|
||||
|
||||
#### Scenario: JavaFX applications share the runtime
|
||||
- **WHEN** Hub-owned application composition has completed
|
||||
- **THEN** Mission Control and Process Manager retain the same `JavaFxRuntimeService` instance registered by the Hub
|
||||
|
||||
#### Scenario: Process Manager is process-discoverable
|
||||
- **WHEN** Hub-owned application composition has completed
|
||||
- **THEN** the object constructed with the current Hub is retrievable as both `NenjimProcessManager` and `NenjimProcess` under `nenjim.process-manager.default`
|
||||
- **THEN** the object constructed with the current Hub and shared JavaFX runtime is retrievable as both `NenjimProcessManager` and `NenjimProcess` under `nenjim.process-manager.default`
|
||||
|
||||
#### Scenario: Required hardcoded bindings are registered
|
||||
- **WHEN** Hub composition completes
|
||||
- **THEN** Journal, the Process Manager, and all component IDs and implementation choices enumerated by issue #76 are present exactly as configured, including intentionally inactive components and excluding both service managers
|
||||
- **THEN** Journal, the JavaFX runtime, the Process Manager, and all component IDs and implementation choices enumerated by issue #76 are present exactly as configured, including intentionally inactive components and excluding both service managers
|
||||
|
||||
#### Scenario: Explicit startup subset preserves order
|
||||
- **WHEN** Hub startup succeeds through the Process Manager phase
|
||||
- **THEN** successful process order is `nenjim.registry.service`, `nenjim.journal.service`, `assetaz.ticker.default`, `evelyn.service.prod`, `evelyn.service.test`, `evelyn.iou-burner.prod`, `evelyn.mission-control.default`, and `nenjim.process-manager.default`
|
||||
- **THEN** successful process order is `nenjim.registry.service`, `nenjim.journal.service`, `assetaz.ticker.default`, `evelyn.service.prod`, `evelyn.service.test`, `evelyn.iou-burner.prod`, `nenjim.javafx-runtime.service`, `evelyn.mission-control.default`, and `nenjim.process-manager.default`
|
||||
|
||||
#### Scenario: Deliberately inactive processes remain inactive
|
||||
- **WHEN** Hub startup reaches its online point
|
||||
@@ -224,6 +232,10 @@ The reference Registry construction boundary SHALL create one Registry object ex
|
||||
- **WHEN** Journal process startup throws
|
||||
- **THEN** Registry remains the only recorded process, no business component is constructed or started, the exception propagates, and the Hub neither announces online nor enters its final wait
|
||||
|
||||
#### Scenario: JavaFX runtime failure is fail-fast
|
||||
- **WHEN** JavaFX runtime service startup throws
|
||||
- **THEN** its ID is not recorded, Mission Control and Process Manager do not start, the exception propagates, and the Hub neither announces online nor enters its final wait
|
||||
|
||||
#### Scenario: Hub start is not retried
|
||||
- **WHEN** any first Hub startup attempt has begun and `start()` is requested again
|
||||
- **THEN** the later request fails with `IllegalStateException` whether the first attempt succeeded or failed
|
||||
@@ -233,7 +245,7 @@ The reference Registry construction boundary SHALL create one Registry object ex
|
||||
- **THEN** the exception propagates, no later process starts, the Hub neither announces online nor enters its final wait, and no generic rollback or retry is attempted
|
||||
|
||||
### Requirement: Started-process snapshots are ordered immutable and truthful
|
||||
`NenjimHub.getStartedProcessIds()` SHALL be safe before, during, and after startup and SHALL return an immutable point-in-time snapshot in successful startup order. A process ID SHALL be appended only after that process's `start()` call returns successfully, including `nenjim.process-manager.default`. Earlier successful entries SHALL remain visible after a later failure, while a failing process SHALL never be included. The snapshot SHALL make no health or continued-liveness guarantee.
|
||||
`NenjimHub.getStartedProcessIds()` SHALL be safe before, during, and after startup and SHALL return an immutable point-in-time snapshot in successful startup order. A process ID SHALL be appended only after that process's `start()` call returns successfully, including `nenjim.javafx-runtime.service` and `nenjim.process-manager.default`. Earlier successful entries SHALL remain visible after a later failure, while a failing process SHALL never be included. The snapshot SHALL make no health or continued-liveness guarantee.
|
||||
|
||||
#### Scenario: Snapshot before process startup
|
||||
- **WHEN** the snapshot is requested before any process has started successfully
|
||||
@@ -243,6 +255,10 @@ The reference Registry construction boundary SHALL create one Registry object ex
|
||||
- **WHEN** a process's `start()` call returns successfully
|
||||
- **THEN** its ID appears after all previously successful process IDs in every later snapshot
|
||||
|
||||
#### Scenario: JavaFX runtime uses the common recording rule
|
||||
- **WHEN** JavaFX runtime service `start()` returns successfully
|
||||
- **THEN** the Hub records `nenjim.javafx-runtime.service` through the same post-start rule used for every other process
|
||||
|
||||
#### Scenario: Process Manager uses the common recording rule
|
||||
- **WHEN** Process Manager `start()` returns successfully
|
||||
- **THEN** the Hub records `nenjim.process-manager.default` through the same post-start rule used for every other process
|
||||
|
||||
@@ -4,7 +4,7 @@
|
||||
TBD - created by archiving change 79-integrate-process-manager-runtime-status. Update Purpose after archive.
|
||||
## Requirements
|
||||
### Requirement: Process Manager is a Hub-managed process
|
||||
`com.r35157.nenjim.npm.NenjimProcessManager` SHALL extend the canonical `NenjimProcess` and SHALL add no public refresh, polling, event, start, stop, or query operation. `NenjimProcessManagerImpl` SHALL require and retain its owning non-null `NenjimHub` as an explicit constructor dependency and SHALL use that Hub as the sole source of displayed process status.
|
||||
`com.r35157.nenjim.npm.NenjimProcessManager` SHALL extend the canonical `NenjimProcess` and SHALL add no public refresh, polling, event, start, stop, or query operation. `NenjimProcessManagerImpl` SHALL require and retain its owning non-null `NenjimHub` as the sole source of displayed process status and the non-null shared `JavaFxRuntimeService` as the sole JavaFX Application Thread submission path.
|
||||
|
||||
#### Scenario: Process Manager is used through the common lifecycle
|
||||
- **WHEN** the registered Process Manager is resolved through `NenjimProcess`
|
||||
@@ -14,12 +14,20 @@ TBD - created by archiving change 79-integrate-process-manager-runtime-status. U
|
||||
- **WHEN** reference Process Manager construction receives a null Hub
|
||||
- **THEN** construction fails with `NullPointerException` before startup
|
||||
|
||||
#### Scenario: JavaFX runtime service is required
|
||||
- **WHEN** reference Process Manager construction receives a null JavaFX runtime service
|
||||
- **THEN** construction fails with `NullPointerException` before startup
|
||||
|
||||
#### Scenario: Public API remains minimal
|
||||
- **WHEN** a consumer examines `NenjimProcessManager`
|
||||
- **THEN** it exposes no Process Manager-specific refresh, polling, event, stop, status, or query method
|
||||
|
||||
### Requirement: Process Manager polls immediately on one non-blocking worker
|
||||
On its accepted startup attempt, the Process Manager SHALL start or reuse the existing JavaFX runtime mechanism, request the existing Process Manager window, and start exactly one dedicated background polling loop. The loop SHALL request `NenjimHub.getStartedProcessIds()` immediately and again after each normal three-second interval. Polling work SHALL not execute on the JavaFX application thread, and the worker SHALL be a daemon that does not prevent JVM termination.
|
||||
On its accepted startup attempt, the Process Manager SHALL request the existing window through its injected already-started `JavaFxRuntimeService` without initializing or starting JavaFX, then start exactly one dedicated background polling loop. The loop SHALL request `NenjimHub.getStartedProcessIds()` immediately and again after each normal three-second interval. Polling work SHALL not execute on the JavaFX Application Thread, and the worker SHALL be a daemon that does not prevent JVM termination.
|
||||
|
||||
#### Scenario: JavaFX prerequisite is unavailable
|
||||
- **WHEN** Process Manager startup submits its window before the injected JavaFX runtime service has started successfully
|
||||
- **THEN** service rejection propagates as Process Manager startup failure and no polling worker starts
|
||||
|
||||
#### Scenario: First snapshot is immediate
|
||||
- **WHEN** Process Manager startup schedules its JavaFX window and starts its polling worker
|
||||
@@ -31,14 +39,14 @@ On its accepted startup attempt, the Process Manager SHALL start or reuse the ex
|
||||
|
||||
#### Scenario: Polling is not JavaFX work
|
||||
- **WHEN** the Hub snapshot is queried and mapped
|
||||
- **THEN** that work runs on the dedicated background polling thread rather than the JavaFX application thread
|
||||
- **THEN** that work runs on the dedicated background polling thread rather than the JavaFX Application Thread
|
||||
|
||||
#### Scenario: Worker does not own JVM lifetime
|
||||
- **WHEN** only the Process Manager polling worker would otherwise keep the JVM alive
|
||||
- **THEN** its daemon status permits normal JVM termination
|
||||
|
||||
### Requirement: Successful snapshots replace the JavaFX list exactly
|
||||
Each successful poll SHALL map every returned `NenjimComponentId` to its exact `value()` string in Hub-provided order and SHALL publish that complete point-in-time list through the existing JavaFX runtime integration. Every JavaFX control mutation SHALL execute on the JavaFX application thread, and publication SHALL replace the complete displayed list rather than infer additions or removals. The existing title, dimensions, and multiple-selection behavior MAY remain unchanged, and no hardcoded process rows SHALL remain.
|
||||
Each successful poll SHALL map every returned `NenjimComponentId` to its exact `value()` string in Hub-provided order and SHALL publish that complete point-in-time list through the injected `JavaFxRuntimeService`. Every JavaFX control mutation SHALL execute on the JavaFX Application Thread, and publication SHALL replace the complete displayed list rather than infer additions or removals. The existing title, dimensions, and multiple-selection behavior MAY remain unchanged, and no hardcoded process rows SHALL remain.
|
||||
|
||||
#### Scenario: Ordered ID values are displayed
|
||||
- **WHEN** the Hub returns an ordered snapshot of component IDs
|
||||
@@ -54,7 +62,7 @@ Each successful poll SHALL map every returned `NenjimComponentId` to its exact `
|
||||
|
||||
#### Scenario: JavaFX controls remain thread-confined
|
||||
- **WHEN** the window is created or a successful snapshot is published
|
||||
- **THEN** all JavaFX control creation and mutation executes through the existing JavaFX runtime on the JavaFX application thread
|
||||
- **THEN** all JavaFX control creation and mutation is submitted through the retained runtime service for execution on the JavaFX Application Thread
|
||||
|
||||
### Requirement: Polling failures preserve the last successful view
|
||||
A polling failure SHALL be logged clearly, SHALL enqueue no invented or partial replacement, SHALL not terminate the JavaFX application thread, and SHALL leave the last successfully displayed snapshot visible. The background loop SHALL retry after the next normal three-second interval. If background waiting is interrupted, the worker SHALL restore its interrupted status and terminate the polling loop cleanly. Synchronous failures from the Process Manager's `start()` SHALL remain ordinary fail-fast Hub process-start failures.
|
||||
|
||||
Reference in New Issue
Block a user