Support $changeStreamSplitLargeEvent

[katcharov]

JAVA-4955

[katcharov]

I did not create a stage builder, since we do not seem to offer stages for other stages like this (for example, $currentOp).

[katcharov]

This is an unfortunate proliferation of constructors, but it seems in line with what was done previously in this class.

[vbabanin]

Should we include a "@deprecated" tag to specify the reason for deprecation?

[katcharov]

I added the following just now,

     * @deprecated Prefer a non-deprecated constructor

but when I read it, it seemed too obvious, like "@deprecated use something that isn't deprecated". I think one convention (apart from not including the tag) is to link to the preferred replacement, but here, I do not think we should do this since there have already been N replacements, so it seemed like a link would become outdated.

If you still think this is worth including, I don't feel too strongly, but let me know the wording.

[stIncMale]

Before the server change supported in this PR, the operationType field of a ChangeStreamDocument (it is called a "change event" in the MongoDB docs) was not optional: https://github.com/mongodb/specifications/blob/master/source/change-streams/change-streams.rst#response-format, and was set in all events (to see that one has to click and look through all events documented in https://www.mongodb.com/docs/v7.0/reference/change-events/, which is, no doubt, convenient). However, that field appear to become optional (a breaking change 🤷‍♂️) since MongoDB 7.0 based on the comments in https://jira.mongodb.org/browse/DRIVERS-2617. Given that this is not documented anywhere (neither in https://www.mongodb.com/docs/v7.0/reference/operator/aggregation/changeStreamSplitLargeEvent/ or https://www.mongodb.com/docs/v7.0/reference/operator/aggregation/changeStream/, nor in https://github.com/mongodb/specifications/blob/master/source/change-streams/change-streams.rst, nor anywhere in https://www.mongodb.com/docs/v7.0/reference/change-events/), this should be clarified. If the field indeed becomes optional, we will need to add @Nullable annotations appropriately to ChangeStreamDocument, and either change the documentation of OperationType.OTHER, or add a new OMITTED value.¹

---

¹ Bizarrely, OperationType.fromString already handles null references (they correspond to missing operationType fields), even though they could not have been missing, and if they were missing, that would have rendered ChangeStreamDocument.getOperationTypeString broken, because the method must not return null (note how ChangeStreamDocument methods that may return null are annotated with @Nullable, for example, getFullDocument).

[stIncMale]

Based on https://mongodb.slack.com/archives/C72LB5RPV/p1689609952334209, it looks like the work required to start supporting $changeStreamSplitLargeEvent in drivers was not done, even though it was supposed to be.

[katcharov]

I'll pause on this part until the changes are completed.

[stIncMale]

Should I resolve this, or is there something you are still waiting for?

[katcharov]

fromString does not take null; note that it is used in the OperationTypeCodec

[stIncMale]

I am glad we are not passing null to OperationType.fromString, even though it (arguably, incorrectly) has the code to handle nulls.

[stIncMale]

I am glad we are not passing null to OperationType.fromString, even though it (arguably, incorrectly) has the code to handle nulls.

[vbabanin]

Should we include a "@deprecated" tag to specify the reason for deprecation?

[vbabanin]

Since SplitEvent works with 6.0.9 and the documentation has been updated for it, let's change it here to 6.0.9 as well

[katcharov]

Good catch