Evolving (driver-core 5.5.0 API) (original) (raw)

Signifies that the annotated program element is subject to incompatible changes by means of adding abstract methods. This, in turn, means that implementing interfaces or extending classes annotated with Evolving bears the risk of doing extra work during upgrades. Using such program elements is no different from using ordinary unannotated program elements. Note that the presence of this annotation implies nothing about the quality or performance of the API in question.

Unless we currently want to allow users to extend/implement API program elements, we must annotate them with@Sealed rather than @Evolving. Replacing @Sealed with @Evolving is a backward-compatible change, while the opposite is not.

Reasons we may allow users to extend/implement an API program element

Reason	Example	Applicability of @Evolving
Doing so allows/simplifies integrating user code with the API.	Bson	Not applicable.
Doing so allows customizing API behavior.	Codec	Not applicable.
Doing so facilitates writing application unit tests by creating a fake implementation.	com.mongodb.client.MongoClient	Applicable.
The program element was introduced before @Evolving.	com.mongodb.client.MongoClient	Applicable.