diff --git a/snooty.toml b/snooty.toml index 3d936f3..ea8e8e2 100644 --- a/snooty.toml +++ b/snooty.toml @@ -12,7 +12,8 @@ toc_landing_pages = [ "/read-data-from-mongo/", "/write-data-to-mongo/", "/getting-started/", - "/secure-your-data/" + "/secure-your-data/", + "/upgrade/" ] [constants] diff --git a/source/index.txt b/source/index.txt index c21fa21..d0a1aa0 100644 --- a/source/index.txt +++ b/source/index.txt @@ -36,7 +36,8 @@ MongoDB Java Reactive Streams Documentation /custom-implementations /whats-new /issues-and-help - /compatibility + /compatibility + /upgrade API Documentation <{+api+}/mongodb-driver-reactivestreams/> Overview @@ -110,6 +111,12 @@ For compatibility tables that show the recommended {+driver-short+} version to use for specific Java and {+mdb-server+} versions, see the :ref:`java-rs-compatibility` section. +Upgrade Driver Versions +----------------------- + +Learn about changes you must make to your application to upgrade driver +versions in the :ref:`` section. + API Documentation ----------------- diff --git a/source/upgrade.txt b/source/upgrade.txt new file mode 100644 index 0000000..a74ecc2 --- /dev/null +++ b/source/upgrade.txt @@ -0,0 +1,451 @@ +.. _java-rs-upgrade-driver: + +======================= +Upgrade Driver Versions +======================= + +.. facet:: + :name: genre + :values: reference + +.. meta:: + :keywords: java, backwards compatibility, update + +.. contents:: On this page + :local: + :backlinks: none + :depth: 2 + :class: singlecol + +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 version is compatible with the {+mdb-server+} versions + your application connects to and the Java Runtime Environment (JRE) your + application runs on. See the :ref:`Compatibiliity page ` + for this information. +- 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 ` section. To learn + more about the {+mdb-server+} release compatibility changes, see the + :ref:`` section. + +.. tip:: + + To minimize the amount of changes your application might require when + upgrading driver versions in the future, use the + :ref:`{+stable-api+} `. + +.. _java-rs-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 v4.0 to v4.5, address all breaking changes from +the version after v4.0 including any listed under v4.5. + +.. _java-rs-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``. This change breaks binary compatibility, so 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 timeout duration parameter in 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. + You can use the ``Filters.eq()`` method when instantiating a + ``VectorSearchOptions`` type, as shown in the following code: + + .. code-block:: java + + VectorSearchOptions opts = vectorSearchOptions().filter(eq("x", 8)); + +.. _java-rs-breaking-changes-v5.0-observables: + +- Removes the + ``org.mongodb.scala.ObservableImplicits.ToSingleObservableVoid`` implicit + class. This means the ``org.reactivestreams.Publisher[Void]`` type no longer + converts automatically to ``org.mongodb.scala.SingleObservable[Void]``. The + API also exposes ``org.mongodb.scala.Observable[Unit]`` instead of + ``org.mongodb.scala.Observable[Void]``. + + For more information, see the `Observable trait in the Scala API documentation + `__. + +- Changes how ``ClusterSettings`` computes + ``ClusterConnectionMode``, making it more consistent by using the specified + replica set name, regardless of how it is configured. Previously, replica set + name was only considered if it was set by the connection string. + + For example, the following two code samples both return the value + ``ClusterConnectionMode.MULTIPLE``, while previously the second one returned + ``ClusterConnectionMode.SINGLE``. + + .. code-block:: java + + ClusterSettings.builder() + .applyConnectionString(new ConnectionString("mongodb://127.0.0.1:27017/?replicaSet=replset")) + .build() + .getMode() + + .. code-block:: java + + ClusterSettings.builder() + .hosts(Collections.singletonList( + new ServerAddress("127.0.0.1", 27017) + )) + .requiredReplicaSetName("replset") + .build() + .getMode() + +- Changes how ``BsonDecimal128`` values respond to method calls, by + responding in the same way as ``Decimal128`` values. In particular, + ``BsonDecimal128.isNumber()`` now returns ``true``, and + ``BsonDecimal128.asNumber()`` returns the equivalent ``BsonNumber``. + +- Removes the `ServerAddress <{+api+}/mongodb-driver-core/com/mongodb/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 <{+api+}/mongodb-driver-core/com/mongodb/UnixServerAddress.html>`__ + methods ``getSocketAddress()`` and ``getUnixSocketAddress()``. + + 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``, see the `UnixSocketAddress `__ 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 page ` in the {+mdb-server+} manual. + +- Removes the ``oplogReplay`` option from find operations. This + includes the following methods: + + - ``DBCursor.oplogReplay()`` + - ``DBCollectionFindOptions.isOplogReplay()`` + - ``DBCollectionFindOptions.oplogReplay()`` + - ``FindPublisher.oplogReplay()`` + - ``FindIterable.oplogReplay()`` + +- Removes the following ``Exception`` constructors: + + - ``MongoBulkWriteException(BulkWriteResult, List, 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)`` + - ``acknowledged(Type, int, Integer, List)`` + - ``acknowledged(int, int, int, Integer, List)`` + +- 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`` + + Because of these removals, the following methods were also removed from the + ``ConnectionPoolListener`` interface: + + - ``connectionAdded`` + - ``connectionPoolOpened`` + - ``connectionRemoved`` + + For more information about the events package, see the `com.mongodb.event + package documentation <{+api+}/mongodb-driver-core/com/mongodb/event/package-summary.html>`__ + +.. _java-rs-breaking-changes-v5.0-list-collections: + +- Adds support for a new ``authorizedCollection`` option of + the ``listCollections`` command. This introduces a breaking binary + change in the ``MongoDatabase.listCollectionNames()`` methods, meaning any + code using these methods must be recompiled. This change does not require any + changes to source code. + +- Removes the following methods and types related to the + `Stream + `__ + interface: + + - ``streamFactoryFactory()`` method from ``MongoClientSettings.Builder``. + Use the ``MongoClientSettings.Builder.transportSettings()`` method instead. + - ``getStreamFactoryFactory()`` method from ``MongoClientSettings``. + Use the ``MongoClientSettings.getTransportSettings()`` method instead. + - ``NettyStreamFactoryFactory`` class. + Use the ``NettyTransportSettings``, creatable by ``TransportSettings.nettyBuilder()`` + and applied through ``MongoClientSettings.Builder.transportSettings()``. + - ``NettyStreamFactory`` class + - ``AsynchronousSocketChannelStreamFactory`` class + - ``AsynchronousSocketChannelStreamFactoryFactory`` class + - ``BufferProvider`` interface + - ``SocketStreamFactory`` class + - ``Stream`` interface + - ``StreamFactory`` interface + - ``StreamFactoryFactory`` interface + - ``TlsChannelStreamFactoryFactory`` class + +.. _java-rs-breaking-changes-v4.8: + +Version 4.8 Breaking Changes +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +- The driver ends support for connecting to {+mdb-server+} versions v3.4 and + earlier. To learn more about this change, see the :ref:`` + section. +- You must add an explicit dependency on the ``org.bson.codecs.record`` + module if your application deploys the driver in an OSGi container and + relies on the driver for encoding and decoding Java records. + +- The ``RecordCodec``, implemented in v4.6, deserialized POJOs and record + classes that are specified as type parameters of ``List`` or ``Map`` fields + of a record as ``Document`` values instead of their respective classes. This + version now deserializes them to the proper record and POJO types. + + For example, the following record class definitions show a ``Book`` record + that contains a ``List`` that receives a ``Chapter`` type parameter: + + .. code-block:: java + + public record Book(String title, List chapters) {} + public record Chapter(Integer number, String text) {} + + Starting in this version, the codec deserializes data in the ``List`` into + ``Chapter`` record classes instead of ``Document`` values. + +.. _java-rs-breaking-changes-v4.7: + +Version 4.7 Breaking Changes +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +- The ``setWindowFields`` builder API is no longer beta. The new builder + breaks binary and source compatibility. See the + `Aggregates API documentation `__ + for information the new ``setWindowFields()`` method signatures. + + If your application uses this builder in a version earlier than v4.7, update + your source code to use the new method signature and rebuild your binary. + +.. _java-rs-breaking-changes-v4.2: + +Version 4.2 Breaking Changes +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +- The ``ObjectId`` class and its ``serialVersionUID`` field were updated + to use a new format that minimizes serialization compatibility issues + across different versions of the driver. + + If an application using this version or later of the driver attempts to + perform Java Object Serialization on any objects that contain an + ``ObjectId`` and were serialized by a prior version of the driver, Java + throws an ``InvalidClassException``. + + To learn more about Java Object Serialization, see the Java + Documentation on `Serializable Objects `__. + +.. _java-rs-breaking-changes-v4.0: + +Version 4.0 Breaking Changes +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +- Several classes and methods marked as deprecated in the 3.12 release + were removed in this version. +- The insert helper methods return an insert result object instead of + ``void``. +- The ``toJson()`` methods on ``BsonDocument``, ``Document``, and + ``DbObject`` return a relaxed JSON format instead of a strict JSON + format. This makes the JSON documents more readable, but can make it more + difficult to identify the BSON type information, such as the difference + between a 32-bit and 64-bit integer. If your application relies on the + strict JSON format, use the strict mode when reading or writing data. +- The default BSON representation of ``java.util.UUID`` value was changed + from ``JAVA_LEGACY`` to ``UNSPECIFIED``. Applications that store or retrieve + UUID values must explicitly specify which representation to use. You can + specify the representation in the ``uuidRepresentation`` property of + ``MongoClientSettings``. + + The UUID representation that you specify strictly controls how the driver + decodes UUIDs. In previous versions of the driver, if you specified the + ``JAVA_LEGACY`` representation, the driver would decode binary objects + of subtypes 3 and 4 as UUIDs. In version 4.0, the ``JAVA_LEGACY`` + representation works only with subtype 3. + + For a list of members in the ``UuidRepresentation`` enum, see the + `v4.0 API documentation `__. + +- The connection pool no longer restricts the number of wait queue threads + or asynchronous tasks that require a connection to MongoDB. The + application will throttle requests as necessary rather than depend on + the driver to throw a ``MongoWaitQueueFullException``. +- The driver no longer logs using the ``java.util.logging`` (JUL) package + and only supports the SLF4J logging framework. +- The embedded and Android drivers were removed. If your application + relies on these drivers, you must continue to use a 3.x Java driver + version. +- The uber JARs, ``mongo-java-driver`` and ``mongodb-driver``, are no + longer published. If your application relies on one of these, you must + switch to either ``mongodb-driver-sync`` or ``mongodb-driver-legacy`` + depending on which API the application uses. Make sure you remove the + uber JARs from your dependencies. +- Updates to several classes introduced binary compatibility breaks, such + as the method signature change to the insert helper methods. Recompile + any classes that link to the driver against this version or later to ensure + that they continue to work. + +.. _java-rs-server-release-changes: + +Server Release Compatibility Changes +------------------------------------ + +A server release compatibility change is a modification +to the {+driver-long+} 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 `__. + +.. _java-rs-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 +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. + +.. _java-rs-server-release-change-v4.8: + +Driver Version 4.8 Server Support Changes +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The v4.8 driver drops support for {+mdb-server+} v3.4 and earlier. +To use the v4.8 driver, your {+mdb-server+} must be v3.6 or later. To learn +how to upgrade your {+mdb-server+} deployment, see :manual:`Release +Notes ` in the {+mdb-server+} manual.