flatMapEach is the per-element analogue of 🖼️ Flat Map Observable for collections. Each element of the source is mapped to an Observable<R>, and the derived collection contains the current value of each element's observable.
Use this when the items in your collection expose observable properties — e.g. a player's display name or an entity's health — and you want a live view of one of those properties across the whole collection.
@Test
void flatMapEachSample() {
DisplayPlayer kfir = new DisplayPlayer("kfir", Observable.mutable("kfir"));
DisplayPlayer lior = new DisplayPlayer("lior", Observable.mutable("lior"));
ListObservable<DisplayPlayer> players = Observable.list();
players.add(kfir);
players.add(lior);
// flatMapEach exposes the current value of each element's inner observable
ListObservable<String> displayNames = players.flatMapEach(DisplayPlayer::displayName);
assertEquals(List.of("kfir", "lior"), displayNames.get());
// updates when any tracked element's inner observable changes
kfir.displayName().set("Kfir Notro");
assertEquals(List.of("Kfir Notro", "lior"), displayNames.get());
// updates when the source collection changes
DisplayPlayer voigon = new DisplayPlayer("voigon", Observable.mutable("voigon"));
players.add(voigon);
assertEquals(List.of("Kfir Notro", "lior", "voigon"), displayNames.get());
players.remove(kfir);
assertEquals(List.of("lior", "voigon"), displayNames.get());
// mutating an element that is no longer tracked does NOT propagate
kfir.displayName().set("ghost");
assertEquals(List.of("lior", "voigon"), displayNames.get());
}
Behavior
Subscribes to each element's inner observable while the element is present in the source.
When an element leaves the source, its inner subscription is released.
Multiple elements may share the same inner observable — it is observed once and stays observed as long as any referencing element is still in the source.
The mapper is invoked at most once per element per source change, not on every inner-value update.
Cached: get() reuses the previous result until the source changes or a tracked inner observable changes.
Notes per collection type
Source
Result
Element duplication
ListObservable<E>
ListObservable<R>
Order and multiplicity preserved — each occurrence resolves to its inner observable's current value