WatchBuilder

Creates a cursor for the changeStream of this collection, as configured by the builder.

The resulting cursor implicitly has a tailable and awaitData behavior, and requires some special handling:

1. The cursor will never be exhausted, unless the change stream is invalidated (see https://docs.mongodb.com/manual/reference/change-events/#invalidate-event). Therefore, you need to ensure that either:

• you consume a bounded number of events from the stream (such as when using collect, foldWhile, etc.)
• you close the cursor explicitly when you no longer need it (the cursor provider needs to support such a functionality)
• you only start a finite number of unbounded cursors which follow the lifecycle of your whole application (for example they will be shut down along with the driver when the app goes down). In particular, using fold with the default unbounded maxSize will yield a Future which will never resolve.

2. The cursor may yield no results within any given finite time bounds, if there are no changes in the underlying collection. Therefore, the Futures resulting from the cursor operations may never resolve. Unless you are in a fully reactive scenario, you may want to add some timeout behavior to the resulting Future. In that case, remember to explicitly close the cursor when the timeout triggers, so that you don't leak the cursor (the cursor provider needs to support such a functionality).

3. New change streams return no data when the cursor is initially established (only subsequent GetMore commands will actually return the subsequent events). Therefore, such a cursor head will always be empty. Only folding the cursor (directly or through a higher-level cursor provider) will provide the next change event.

4. Resumed change streams (via id or operation time) will return the next event when the cursor is initially established, if there is is some next event. Therefore, head is guaranteed to eventually return the next change event beyond the resume point, when such an event appears.