[kinyoklion]

Summary

This adds the file-based override source that the OVERRIDE specification defines, as FileOverrides.source() in the integrations package, configured through DataSystemBuilder.overrides(...):

LDConfig config = new LDConfig.Builder()
    .dataSystem(Components.dataSystem().defaultMode()
        .overrides(FileOverrides.source().filePaths("/etc/launchdarkly/overrides.json")))
    .build();

The source reads one or more JSON or YAML files in the file data source document format (flags, flagValues, segments) in the configured order. A flagValues entry becomes a flag that is on and serves the value as its single variation by fallthrough, so it evaluates with the FALLTHROUGH reason kind. Entries keep the versions that the documents specify.

• duplicateKeysHandling: FAIL (the default) fails the reload when the same key appears in more than one file; IGNORE keeps the entry from the first configured file.
• changeDetection: POLLING (the default) examines each file's modification time and size on an interval; WATCHING uses file system notifications. The two are alternatives. When the watch service cannot be created at all (for example, the limit on inotify instances is reached), the source logs an error and polls the files instead, at no less than the minimum poll interval.
• pollInterval: one second by default and at minimum; a smaller value is raised to the minimum with a warning.
• A configured file that does not exist contributes no overrides and is not an error. Creating it later takes effect, and deleting it removes its overrides.
• A file that exists but cannot be read or parsed fails that whole reload: the last good overrides stay in effect, the failure is logged, and the source retries after a bounded delay as well as on the next change.
• The initial load completes during client construction. Every applied change is logged at Info with the overrides in effect and what each file supplied.
• No file paths, a null change detection mode, a null poll interval, or a file path that is not on the default file system (a zip file system, for example) with WATCHING selected is a configuration error that fails client construction. Polling reads such a path through its own provider. A path listed more than once is logged at Warn and the repeats are ignored; the first occurrence keeps its place in the order.

The source is built on OverrideFileLoader, FileDataReloader, FileDataPoller, and FileDataWatcher from the earlier change. The existing file data source keeps its current behavior; this change does not touch its code paths. Flag overrides are currently experimental and subject to change.

This PR depends on the override layer and the reload infrastructure changes and is based on the events branch (rlamb/overrides-java-override-events); retarget it to feat/overrides once that branch merges.

SDK-3246

---

Note

Overview
Adds FileOverrides.source() as the public way to load experimental flag/segment overrides from local JSON or YAML files via DataSystemBuilder.overrides(...), so operators can pin flags during outages without changing the main file data source.

The new builder supports multiple files (ordered merge, duplicate-key FAIL/IGNORE), polling vs file watching (with watch failures falling back to polling), poll interval clamping, and validation (paths required, WATCHING limited to the default file system). FileOverrideSourceImpl performs a synchronous initial load, pushes full snapshots to the override sink, keeps the last good set on parse/read errors with retries, and logs what each file contributed.

Docs on OverrideSource and DataSystemBuilder.overrides now point at FileOverrides. Tests cover reload behavior, edge cases, and client CLIENT_SIDE_ONLY behavior for flagValues vs full flags definitions.

^{Reviewed by Cursor Bugbot for commit 8ccc74b. Bugbot is set up for automated code reviews on this repo. Configure here.}

_{Opened from termag}

[kinyoklion]

bugbot review

[cursor]

Stale Bugbot comment from a previous run.

[kinyoklion]

bugbot review

[cursor]

Stale Bugbot comment from a previous run.

[kinyoklion]

bugbot review

[cursor]

Stale Bugbot comment from a previous run.

[kinyoklion]

bugbot review

[cursor]

✅ Bugbot reviewed your changes and found no new issues!

Comment @cursor review or bugbot run to trigger another review on this PR

^{Reviewed by Cursor Bugbot for commit 8ccc74b. Configure here.}