DOCSP-51349: Upgrade guide

source/reference/upgrade.txt

@@ -8,4 +8,389 @@
    :local:
    :backlinks: none
    :depth: 1
-   :class: singlecol
+   :class: singlecol
+
+.. meta::
+   :keywords: backwards compatibility, update
+
+Overview
+--------
+
+In this section, you can identify the changes you must
+make to your application to upgrade your driver to a new version.
+
+Before you upgrade, perform the following actions:
+
+- Ensure the new driver version is compatible with the {+mdb-server+} versions
+  your application connects to and the Java Runtime Environment (JRE) your
+  application runs on. To view compatibility information, see the
+  :ref:`Compatibility <kotlin-sync-compatibility>` page.
+- Address any breaking changes between the current version of the driver
+  your application is using and your planned upgrade version in the
+  :ref:`Breaking Changes <kotlin-sync-breaking-changes>` section. To learn
+  more about {+mdb-server+} release compatibility changes, see the
+  :ref:`<kotlin-sync-server-release-changes>` section.
+
+.. tip::
+
+   To minimize the number of changes your application might require when
+   you upgrade driver versions in the future, use the
+   :ref:`{+stable-api+}. <kotlin-sync-stable-api>`
+
+.. _kotlin-sync-breaking-changes:
+
+Breaking Changes
+----------------
+
+A breaking change is a modification in a convention or behavior in
+a specific version of the driver that might prevent your application from
+working properly if not addressed before upgrading.
+
+The breaking changes in this section are categorized by the driver version that
+introduced them. When upgrading driver versions, address all the breaking
+changes between the current and upgrade versions. For example, if you
+are upgrading the driver from v5.0 to v5.5, address all breaking changes from
+the version after v5.0 including any listed for v5.5.
+
+.. _kotlin-sync-breaking-changes-v5.5:
+
+Version 5.5 Breaking Changes
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+- The driver is no longer compatible with {+mdb-server+} version
+  4.0. To learn more about this change, see the
+  :ref:`kotlin-sync-server-release-change-v5.5` section.
+
+.. _kotlin-sync-breaking-changes-v5.2:
+
+Version 5.2 Breaking Changes
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+This driver version introduces the following breaking changes:
+
+- Drops support for {+mdb-server+} v3.6. To learn more about this change,
+  see the :ref:`<kotlin-sync-server-release-change-v5.2>` section.
+
+- Revises the `mongodb-crypt <https://mvnrepository.com/artifact/org.mongodb/mongodb-crypt>`__
+  dependency versioning to match the versioning for the JVM drivers. Future versions of
+  ``mongodb-crypt`` will be released alongside the driver and will share the same version number.
+  You must upgrade your ``mongodb-crypt`` dependency to v5.2.0 when upgrading your driver for
+  this release.
+
+.. _kotlin-sync-breaking-changes-v5.1:
+
+Version 5.1 Breaking Changes
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+This driver version introduces the following breaking changes:
+
+- When using the ``MONGODB-OIDC`` authentication mechanism, you must
+  not include comma characters in the ``authMechanismProperties`` connection
+  string value.
+
+.. _kotlin-sync-breaking-changes-v5.0:
+
+Version 5.0 Breaking Changes
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+This driver version introduces the following breaking changes:
+
+- Introduces the following changes to the ``ConnectionId`` class:
+
+  - The ``ConnectionId`` constructor now accepts a value of type ``long`` as its second
+    parameter instead of type ``int``. Similarly, the constructor now accepts a value of
+    type ``Long`` as its third parameter instead of type ``Integer``. Because this change breaks
+    binary compatibility, recompile any existing code that calls the
+    ``ConnectionId`` constructor.
+
+  - The ``withServerValue()`` method now accepts a parameter of type ``long`` rather than
+    type ``int``. Because this change breaks binary compatibility, you must recompile any code
+    that calls the ``withServerValue()`` method.
+
+  - The ``getServerValue()`` method now returns a value of type ``Long`` instead of type
+    ``Integer``. Similarly, the ``getLocalValue()`` method returns a value of type
+    ``long`` instead of type ``int``. Because this change breaks both binary and source
+    compatibility, update any source code that uses these methods and rebuild your binary.
+
+- Replaces the following record annotations from the
+  ``org.bson.codecs.record.annotations`` package with
+  annotations of the same name from the ``org.bson.codecs.pojo.annotations`` package:
+
+  - ``BsonId``
+  - ``BsonProperty``
+  - ``BsonRepresentation``
+
+- Changes the data type of the ``connectTimeout`` timeout duration parameter for the
+  ``SocketSettings.Builder.connectTimeout()`` and
+  ``SocketSettings.Builder.readTimeout()`` methods. The data type of this
+  parameter is now ``long`` instead of ``int``.
+
+  In earlier versions, this parameter is of type ``int`` for both methods. This
+  change breaks binary compatibility and requires recompiling, but does not
+  require code changes.
+
+- Removes the ``Filters.eqFull()`` method, released
+  exclusively in ``Beta``, which allowed you
+  to construct an equality filter when performing a vector search.
+  Instead, you can use the ``Filters.eq()`` method when instantiating a
+  ``VectorSearchOptions`` type, as shown in the following code:
+
+  .. code-block:: kotlin
+
+     val opts = vectorSearchOptions().filter(eq("x", 8))
+
+- Changes how ``ClusterSettings`` computes the ``ClusterConnectionMode``
+  setting, making it more consistent by using the specified
+  replica set name, regardless of how it is configured. Previously, the driver
+  considered the replica set name only if it was set in the connection string.
+
+  For example, the following two code samples both return the value
+  ``ClusterConnectionMode.MULTIPLE``. Previously, the second example returned
+  ``ClusterConnectionMode.SINGLE``.
+
+  .. code-block:: kotlin
+
+     ClusterSettings.builder()
+         .applyConnectionString(ConnectionString("mongodb://127.0.0.1:27017/?replicaSet=replset"))
+         .build()
+         .mode
+
+  .. code-block:: kotlin
+
+     ClusterSettings.builder()
+         .hosts(listOf(ServerAddress("127.0.0.1", 27017)))
+         .requiredReplicaSetName("replset")
+         .build()
+         .mode
+
+- ``BsonDecimal128`` values respond to method calls in the same way as
+  ``Decimal128`` values. ``BsonDecimal128.isNumber()`` now returns ``true`` and
+  ``BsonDecimal128.asNumber()`` returns the equivalent ``BsonNumber``.
+
+- Removes the `ServerAddress <{+core-api+}/ServerAddress.html>`__
+  methods ``getSocketAddress()`` and ``getSocketAddresses()``.
+
+  Instead of ``getSocketAddress()``, use the ``getByName()`` instance
+  method of ``java.net.InetAddress``.
+
+  Instead of ``getSocketAddresses()``, use the ``getAllByName()`` instance
+  method of ``java.net.InetAddress``.
+
+- Removes the `UnixServerAddress <{+core-api+}/UnixServerAddress.html>`__
+  methods ``getSocketAddress()`` and ``getUnixSocketAddress()``.
+
+  Instead of ``getSocketAddress()``, use the ``getByName()`` instance
+  method of ``java.net.InetAddress``.
+
+  Instead of ``getUnixSocketAddress()``, construct an instance of
+  ``jnr.unixsocket.UnixSocketAddress``. Pass the full path of the UNIX
+  socket file to the constructor. By default, MongoDB creates a UNIX
+  socket file located at ``"/tmp/mongodb-27017.sock"``. To learn more
+  about the ``UnixSocketAddress`` class, see the `UnixSocketAddress <https://www.javadoc.io/doc/com.github.jnr/jnr-unixsocket/latest/jnr/unixsocket/UnixSocketAddress.html>`__ API documentation.
+
+- Removes the ``Parameterizable`` interface. Instead of
+  implementing this interface on a custom ``Codec`` type,
+  override the ``CodecProvider.get()`` method on the
+  codec's ``CodecProvider`` if the codec is intended for a parameterized
+  type.
+
+- Removes the ``isSlaveOk()`` method from the
+  ``ReadPreference`` and ``TaggableReadPreference`` classes. To check whether a read preference allows
+  reading from a secondary member of a replica set, use the ``isSecondaryOk()`` methods from
+  these classes instead.
+
+- Removes the ``DBCollection.getStats()`` and ``DBCollection.isCapped()``
+  helper methods for the ``collStats`` command. Instead of these methods, you can use the
+  ``$collStats`` aggregation pipeline stage.
+
+- Removes the ``MapCodec`` and ``IterableCodec`` classes.
+  Instead of ``MapCodec``, use ``MapCodecProvider``. Instead of ``IterableCodec``,
+  use ``CollectionCodecProvider``, or ``IterableCodecProvider`` for ``Iterable``
+  types that aren't ``Collection`` types.
+
+- Removes the ``sharded()`` and ``nonAtomic()`` methods from the
+  ``MapReducePublisher`` and ``MapReduceIterable`` classes.
+
+- Removes the following methods for use with ``geoHaystack`` indexes:
+
+  - ``Indexes.geoHaystack()``
+  - ``IndexOptions.getBucketSize()``
+  - ``IndexOptions.bucketSize()``
+
+  Instead, you can use the ``$geoNear`` aggregation pipeline stage or a geospatial
+  query operator on a 2d index. For more information, see the
+  :manual:`Geospatial Queries </geospatial-queries>` page in the {+mdb-server+} manual.
+
+- Removes the ``oplogReplay`` option from find operations. The
+  following ``oplogReplay`` methods are no longer available:
+
+  - ``DBCursor.oplogReplay()``
+  - ``DBCollectionFindOptions.isOplogReplay()``
+  - ``DBCollectionFindOptions.oplogReplay()``
+  - ``FindPublisher.oplogReplay()``
+  - ``FindIterable.oplogReplay()``
+
+- Removes the following ``Exception`` constructors:
+
+  - ``MongoBulkWriteException(BulkWriteResult, List<BulkWriteError>, WriteConcernError, ServerAddress)``
+  - ``MongoCursorNotFoundException(long, ServerAddress)``
+  - ``MongoQueryException(ServerAddress, int, String)``
+  - ``MongoQueryException(ServerAddress, int, String, String)``
+  - ``MongoQueryException(MongoCommandException)``
+
+- Removes the following overloads for the ``BulkWriteResult.acknowledged()`` method:
+
+  - ``acknowledged(Type, int, List<BulkWriteUpsert>)``
+  - ``acknowledged(Type, int, Integer, List<BulkWriteUpsert>)``
+  - ``acknowledged(int, int, int, Integer, List<BulkWriteUpsert>)``
+
+- Removes the following ``ChangeStreamDocument`` constructors:
+
+  - ``ChangeStreamDocument(String, BsonDocument, BsonDocument, BsonDocument,
+    TDocument, TDocument, BsonDocument, ...)``
+  - ``ChangeStreamDocument(String, BsonDocument, BsonDocument, BsonDocument,
+    TDocument, BsonDocument, BsonTimestamp, ...)``
+  - ``ChangeStreamDocument(OperationType, BsonDocument, BsonDocument, BsonDocument,
+    TDocument, BsonDocument, BsonTimestamp, ...)``
+
+- Removes the following constructors for events:
+
+  - ``CommandEvent(RequestContext, int, ConnectionDescription, String)``
+  - ``CommandEvent(int, ConnectionDescription, String)``
+  - ``CommandEvent(RequestContext, long, int, ConnectionDescription, String)``
+  - ``CommandFailedEvent(RequestContext, int, ConnectionDescription, String,
+    long, Throwable)``
+  - ``CommandFailedEvent(int, ConnectionDescription, String, long, Throwable)``
+  - ``CommandStartedEvent(RequestContext, int, ConnectionDescription, String,
+    String, BsonDocument)``
+  - ``CommandStartedEvent(int, ConnectionDescription, String, String, BsonDocument)``
+  - ``CommandSucceededEvent(RequestContext, int, ConnectionDescription, String,
+    BsonDocument, long)``
+  - ``CommandSucceededEvent(int, ConnectionDescription, String, BsonDocument, long)``
+  - ``ConnectionCheckedInEvent(ConnectionId)``
+  - ``ConnectionCheckedOutEvent(ConnectionId, long)``
+  - ``ConnectionCheckedOutEvent(ConnectionId)``
+  - ``ConnectionCheckOutFailedEvent(ServerId, long, Reason)``
+  - ``ConnectionCheckOutFailedEvent(ServerId, Reason)``
+  - ``ConnectionCheckOutStartedEvent(ServerId)``
+  - ``ConnectionReadyEvent(ConnectionId)``
+  - ``ServerHeartbeatFailedEvent(ConnectionId, long, Throwable)``
+  - ``ServerHeartbeatSucceededEvent(ConnectionId, BsonDocument, long)``
+
+- Removes the ``errorLabels`` option from the ``WriteConcernError``
+  class. This includes the ``addLabel()`` and ``getErrorLabels()`` methods and the
+  constructor that includes an ``errorLabels`` parameter. Instead, you can use
+  the error labels included in the ``MongoException`` object that contains the
+  ``WriteConcernError``.
+
+- Removes the following classes from the
+  ``com.mongodb.event`` package:
+
+  - ``ConnectionAddedEvent``
+  - ``ConnectionPoolOpenedEvent``
+  - ``ConnectionRemovedEvent``
+  - ``ClusterListenerAdapter``
+  - ``ConnectionPoolListenerAdapter``
+  - ``ServerListenerAdapter``
+  - ``ServerMonitorListenerAdapter``
+
+  The driver also removes the following related methods from the
+  ``ConnectionPoolListener`` interface:
+
+  - ``connectionAdded()``
+  - ``connectionPoolOpened()``
+  - ``connectionRemoved()``
+
+  For more information about the ``com.mongodb.event`` package, see the
+  `API documentation. <{+core-api+}/event/package-summary.html>`__
+
+.. _kotlin-sync-breaking-changes-v5.0-list-collections:
+
+- Adds the ``authorizedCollection`` option for the ``listCollections`` command.
+  This introduces a breaking binary change in the ``MongoDatabase.listCollectionNames()``
+  method. This change does not require any changes to source code, but you must
+  recompile any code that uses this method.
+
+- Removes the following methods and types related to the
+  `Stream
+  <https://mongodb.github.io/mongo-java-driver/4.11/apidocs/mongodb-driver-core/com/mongodb/connection/Stream.html>`__
+  interface:
+
+  - ``MongoClientSettings.Builder.streamFactoryFactory()`` method.
+    Use the ``MongoClientSettings.Builder.transportSettings()`` method instead.
+  - ``MongoClientSettings.getStreamFactoryFactory()`` method.
+    Use the ``MongoClientSettings.getTransportSettings()`` method instead.
+  - ``NettyStreamFactoryFactory`` class.
+    Instead, call the ``TransportSettings.nettyBuilder()`` method to create
+    a ``NettyTransportSettings`` object. Then, call the ``MongoClientSettings.Builder.transportSettings()``
+    method to apply the settings.
+  - ``NettyStreamFactory`` class.
+  - ``AsynchronousSocketChannelStreamFactory`` class.
+  - ``AsynchronousSocketChannelStreamFactoryFactory`` class.
+  - ``BufferProvider`` interface.
+  - ``SocketStreamFactory`` class.
+  - ``Stream`` interface.
+  - ``StreamFactory`` interface.
+  - ``StreamFactoryFactory`` interface.
+  - ``TlsChannelStreamFactoryFactory`` class.
+
+.. tip::
+
+   To view breaking changes for earlier driver versions, see the
+   :github:`Release Notes <mongodb/mongo-java-driver/releases>` in the 
+   ``mongo-java-driver`` GitHub repository.
+
+.. _kotlin-sync-server-release-changes:
+
+Server Release Compatibility Changes
+------------------------------------
+
+A server release compatibility change is a modification
+to the {+driver-short+} that discontinues support for a set of
+{+mdb-server+} versions.
+
+The driver discontinues support for a {+mdb-server+} version after it reaches
+end-of-life (EOL).
+
+To learn more about the MongoDB support for EOL products,
+see the `Legacy Support Policy <https://www.mongodb.com/support-policy/legacy>`__.
+
+.. _kotlin-sync-server-8.1-incompatibility:
+
+Server Version 8.1 Support Changes
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+You cannot use a 3.x version of the {+driver-short+} to connect to a
+MongoDB deployment running {+mdb-server+} v8.1. Starting in {+mdb-server+} v8.1,
+the ``buildinfo`` command requires authentication, causing an
+incompatibility with the v3.x driver.
+
+.. _kotlin-sync-server-release-change-v5.5:
+
+Driver Version 5.5 Server Support Changes
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The v5.5 driver drops support for {+mdb-server+} 4.0.
+To use the v5.5 driver, you must connect to {+mdb-server+} 4.2 or later. To
+learn how to upgrade your {+mdb-server+} deployment, see
+:manual:`Release Notes </release-notes>` in the {+mdb-server+} manual.
+
+.. _kotlin-sync-server-release-change-v5.2:
+
+Driver Version 5.2 Server Support Changes
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The v5.2 driver drops support for {+mdb-server+} 3.6.
+To use the v5.2 driver, you must connect to {+mdb-server+} 4.0 or later. To
+learn how to upgrade your {+mdb-server+} deployment, see
+:manual:`Release Notes </release-notes>` in the {+mdb-server+} manual.
+
+.. _kotlin-sync-server-release-change-v4.8:
+
+Driver Version 4.8 Server Support Changes
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The v4.8 driver drops support for {+mdb-server+} 3.4 and earlier.
+To use the v4.8 driver, you must connect to {+mdb-server+} 3.6 or later. To learn
+how to upgrade your {+mdb-server+} deployment, see :manual:`Release
+Notes </release-notes>` in the {+mdb-server+} manual.