docs(eventing): refresh page content and add event source hierarchy#3369
Open
Dennis-Mircea wants to merge 3 commits into
Open
docs(eventing): refresh page content and add event source hierarchy#3369Dennis-Mircea wants to merge 3 commits into
Dennis-Mircea wants to merge 3 commits into
Conversation
Signed-off-by: Dennis-Mircea Ciupitu <dennis.mircea.ciupitu@gmail.com>
Contributor
There was a problem hiding this comment.
Pull request overview
Note
Copilot was unable to run its full agentic suite in this review.
Updates the Eventing documentation to clarify event source concepts, refresh diagrams, and align references/examples with the current repository structure.
Changes:
- Rewrites introductory sections for clearer event-source and dispatch-flow explanations.
- Updates Mermaid diagrams to include
EventProcessor,TimerEventSource, and internal components. - Refreshes GitHub links and modernizes the “Registering Event Sources” example snippet.
Comment on lines
+95
to
104
| public class WebPageReconciler implements Reconciler<WebPage> { | ||
|
|
||
| @Override | ||
| public List<EventSource<?, Webapp>> prepareEventSources(EventSourceContext<Webapp> context) { | ||
| InformerEventSourceConfiguration<Webapp> configuration = | ||
| InformerEventSourceConfiguration.from(Deployment.class, Webapp.class) | ||
| public List<EventSource<?, WebPage>> prepareEventSources(EventSourceContext<WebPage> context) { | ||
| var configuration = | ||
| InformerEventSourceConfiguration.from(Deployment.class, WebPage.class) | ||
| .withLabelSelector(SELECTOR) | ||
| .build(); | ||
| return List.of(new InformerEventSource<>(configuration, context)); | ||
| } |
Comment on lines
+47
to
+59
| - The `ControllerEventSource` is a special, internal event source responsible for handling events | ||
| pertaining to changes affecting the primary resource. The SDK registers it automatically for every | ||
| controller and you never instantiate it yourself. | ||
| - Every controller also gets a dedicated `TimerEventSource` (named | ||
| `RetryAndRescheduleTimerEventSource`) that the SDK uses to drive retry attempts after a failed | ||
| reconciliation, `UpdateControl.rescheduleAfter(...)` requests, and the periodic max-interval | ||
| failsafe trigger. The `EventProcessor` is the sole caller into this timer, scheduling delayed | ||
| events back to itself via `scheduleOnce(...)`. Like the controller event source, this one is | ||
| wired internally and is not something you register or interact with directly. | ||
| - Once an event reaches the `EventProcessor`, dispatch is delegated to the | ||
| `ReconciliationDispatcher`, which prepares the execution context, handles finalizers and other | ||
| framework concerns, and ultimately invokes `reconcile(...)` on the internal `Controller` wrapper, | ||
| which in turn calls the user-implemented `Reconciler`. |
Signed-off-by: Dennis-Mircea Ciupitu <dennis.mircea.ciupitu@gmail.com>
csviri
requested changes
May 25, 2026
Collaborator
csviri
left a comment
csviri
left a comment
There was a problem hiding this comment.
Thank you @Dennis-Mircea awesome! I just added one comment to discuss with TimerEventSource. pls take a look
| back to the `EventProcessor`, namely retry attempts after a failed reconciliation, explicit | ||
| rescheduling requests via `UpdateControl.rescheduleAfter(...)`, and the periodic failsafe trigger | ||
| governed by `maxReconciliationInterval`. As with `ControllerEventSource`, this is not something | ||
| you instantiate or configure directly. `TimerEventSource` is also available as a public type if |
Collaborator
There was a problem hiding this comment.
This I would not propagate like this. Note that TimerEventSource at this time is only for internal usage, there are other approaches dedicated for periodic reconciliation if needed. (Mostly reSchedule but also:
So we should not propagate it as public api.
Contributor
Author
There was a problem hiding this comment.
Good point, thanks! I reframed it as internal-only, dropped the line implying it can be reused, and pointed readers at UpdateControl.rescheduleAfter(...) / maxReconciliationInterval for periodic or delayed reconciliation instead.
Signed-off-by: Dennis-Mircea Ciupitu <dennis.mircea.ciupitu@gmail.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Refreshes
docs/content/en/docs/documentation/eventing.md, which had drifted from the current code on several fronts and was missing an overview of the event source class hierarchy.Highlights:
Timer Event SourcealongsideController Event Sourceas the second SDK-managed event source. The latter was previously labeled "Custom Resource Event Source", which is not a real class. The dispatcher box was also renamed from "Event Handler" to "Event Processor" to match the actualEventProcessorclass.TimerEventSource(previously unmentioned) alongsideControllerEventSource, namesRetryAndRescheduleTimerEventSourceas the runtime identifier, and walks through the real dispatch chainEventProcessor→ReconciliationDispatcher→Controller.reconcile(...)→ userReconciler.EventSourceInitializer<Webapp>(no longer exists) and the bogusWebapp/WebappReconcilernaming. The snippet now matches the actualWebPageReconcilerinsample-operators/webpage/, withprepareEventSourcescorrectly described as a default method onReconciler.ControllerResourceEventSource→ControllerEventSourcein the heading and link (the class was renamed in 2021 via commit86245ca6; the page still carried the old name and a 404 link).TimerEventSourcesubsection underBuilt-in EventSourcesdocumenting the second auto-registered built-in.Built-in EventSources(mermaidgraph TD) showing howInformerEventSource/ControllerEventSourceshareManagedInformerEventSource, howPollingEventSource/PerResourcePollingEventSource/CachingInboundEventSourceshareExternalResourceCachingEventSource, and whereTimerEventSourceandSimpleInboundEventSourcefit. Distinct colors for interface, abstract classes, plain concretes, and the two SDK-managed built-ins.Caching and Event Sourcespointed to areturn;statement insideFetchingExecutor.run()(line 146). It now points togetSecondaryResources(#L160-L180), which is the method the surrounding prose is actually describing.github.com/java-operator-sdk/java-operator-sdktogithub.com/operator-framework/java-operator-sdkacross the page (the old URLs still redirect, but the page mixed both orgs).No code changes. Docs only.
Fixes #3368