docs(eventing): refresh page content and add event source hierarchy by Dennis-Mircea · Pull Request #3369 · operator-framework/java-operator-sdk · GitHub

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:

Flow diagram updated. The mermaid diagram at the top of the page now includes Timer Event Source alongside Controller Event Source as 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 actual EventProcessor class.
Intro paragraph rewrite. Split the single dense paragraph into three shorter ones, fixed the broken sentence ("Event sources act as listen to events..."), and standardized the voice to second person.
Fixed the post-diagram explanation. The "There are few interesting points here:" paragraph is now an actual bullet list. It mentions TimerEventSource (previously unmentioned) alongside ControllerEventSource, names RetryAndRescheduleTimerEventSource as the runtime identifier, and walks through the real dispatch chain EventProcessor → ReconciliationDispatcher → Controller.reconcile(...) → user Reconciler.
Updated the registration code snippet. Removed references to EventSourceInitializer<Webapp> (no longer exists) and the bogus Webapp / WebappReconciler naming. The snippet now matches the actual WebPageReconciler in sample-operators/webpage/, with prepareEventSources correctly described as a default method on Reconciler.
Renamed ControllerResourceEventSource → ControllerEventSource in the heading and link (the class was renamed in 2021 via commit 86245ca6; the page still carried the old name and a 404 link).
Added a TimerEventSource subsection under Built-in EventSources documenting the second auto-registered built-in.
Added an event source hierarchy diagram at the top of Built-in EventSources (mermaid graph TD) showing how InformerEventSource / ControllerEventSource share ManagedInformerEventSource, how PollingEventSource / PerResourcePollingEventSource / CachingInboundEventSource share ExternalResourceCachingEventSource, and where TimerEventSource and SimpleInboundEventSource fit. Distinct colors for interface, abstract classes, plain concretes, and the two SDK-managed built-ins.
Fixed a stale code link. The "related method" link in Caching and Event Sources pointed to a return; statement inside FetchingExecutor.run() (line 146). It now points to getSecondaryResources (#L160-L180), which is the method the surrounding prose is actually describing.
Normalized GitHub org in inline links from github.com/java-operator-sdk/java-operator-sdk to github.com/operator-framework/java-operator-sdk across the page (the old URLs still redirect, but the page mixed both orgs).

No code changes. Docs only.

Fixes #3368

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.

@Dennis-Mircea I basically agree with this comment, there is a separate architecture and internals page:
https://javaoperatorsdk.io/docs/documentation/architecture/
Where such level of details can be expressed.

But we can improve this in a separate PR.

Nice, thanks!

Thank you @Dennis-Mircea awesome! I just added one comment to discuss with TimerEventSource. pls take a look

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:

java-operator-sdk/operator-framework-core/src/main/java/io/javaoperatorsdk/operator/api/reconciler/ControllerConfiguration.java

Line 68 in afa83b9

MaxReconciliationInterval maxReconciliationInterval() default

So we should not propagate it as public api.

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>

LGTM

Thank you @Dennis-Mircea !

Copilot AI review requested due to automatic review settings May 21, 2026 17:01

openshift-ci Bot requested review from metacosm and xstefank May 21, 2026 17:01

Copilot AI reviewed May 21, 2026

View reviewed changes

xstefank approved these changes May 22, 2026

View reviewed changes

xstefank requested a review from csviri May 22, 2026 06:34

csviri requested changes May 25, 2026

View reviewed changes

Dennis-Mircea requested a review from csviri May 25, 2026 12:50

Dennis-Mircea added 3 commits May 26, 2026 08:47

docs(eventing): refresh page content and add event source hierarchy

78827fe

Signed-off-by: Dennis-Mircea Ciupitu <dennis.mircea.ciupitu@gmail.com>

docs(eventing): Add Copilot suggestion

7f75135

Signed-off-by: Dennis-Mircea Ciupitu <dennis.mircea.ciupitu@gmail.com>

Address review comment

9a0341c

Signed-off-by: Dennis-Mircea Ciupitu <dennis.mircea.ciupitu@gmail.com>

csviri force-pushed the docs/refresh-eventing-page branch from 479d0fe to 9a0341c Compare May 26, 2026 06:47

csviri approved these changes May 26, 2026

View reviewed changes

csviri merged commit f50b74a into operator-framework:main May 26, 2026
1 check passed

+              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));
                   }

+              - 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`.

+              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

docs(eventing): refresh page content and add event source hierarchy by Dennis-Mircea · Pull Request #3369 · operator-framework/java-operator-sdk · GitHub

Uh oh!

docs(eventing): refresh page content and add event source hierarchy - #3369

docs(eventing): refresh page content and add event source hierarchy#3369
csviri merged 3 commits into
operator-framework:mainfrom
Dennis-Mircea:docs/refresh-eventing-page

Dennis-Mircea commented May 21, 2026

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

csviri May 26, 2026

Uh oh!

csviri May 26, 2026

Uh oh!

xstefank left a comment

Uh oh!

csviri left a comment

Uh oh!

csviri May 25, 2026

Uh oh!

Dennis-Mircea May 25, 2026

Uh oh!

csviri left a comment

Uh oh!

Uh oh!

csviri commented May 26, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

docs(eventing): refresh page content and add event source hierarchy by Dennis-Mircea · Pull Request #3369 · operator-framework/java-operator-sdk · GitHub

Uh oh!

docs(eventing): refresh page content and add event source hierarchy - #3369

Conversation

Dennis-Mircea commented May 21, 2026

Summary

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

csviri May 26, 2026

Choose a reason for hiding this comment

Uh oh!

csviri May 26, 2026

Choose a reason for hiding this comment

Uh oh!

xstefank left a comment

Choose a reason for hiding this comment

Uh oh!

csviri left a comment

Choose a reason for hiding this comment

Uh oh!

csviri May 25, 2026

Choose a reason for hiding this comment

Uh oh!

Dennis-Mircea May 25, 2026

Choose a reason for hiding this comment

Uh oh!

csviri left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

csviri commented May 26, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants