From 50e87f796573fdc681fe53cd3f66214d2f17436b Mon Sep 17 00:00:00 2001 From: Nora Reidy Date: Wed, 8 May 2024 10:26:50 -0400 Subject: [PATCH 01/37] DOCSP-39269: Add OIDC to What's New (#544) (cherry picked from commit 8701b75fcb545ee90bd9ba9cfcb096cc80f605ed) --- source/whats-new.txt | 2 ++ 1 file changed, 2 insertions(+) diff --git a/source/whats-new.txt b/source/whats-new.txt index df8264921..efe6d220a 100644 --- a/source/whats-new.txt +++ b/source/whats-new.txt @@ -69,6 +69,8 @@ Improvements in 5.1 - Internal testing of GraalVM native image technology. These tests involve building native applications by using the GraalVM native-image tool. +- Enhanced support for the MONGODB-OIDC authentication mechanism. For more information about + OIDC, see the :ref:`mongodb-oidc` section of the Enterprise Authentication Mechanisms guide. .. _java-new-features-5.1: From 35cfe92c5fc140c14a651674033ac73d76616726 Mon Sep 17 00:00:00 2001 From: Rea Rustagi <85902999+rustagir@users.noreply.github.com> Date: Mon, 3 Jun 2024 09:44:25 -0400 Subject: [PATCH 02/37] DOCSP-30349: server selection errors (#548) * DOCSP-30349: server sel errors * NR PR fixes 1 * JY tech review * fixes * anchor * vale fix (cherry picked from commit aad1fae51772b891dabf6c6edff4eec817b2cc05) --- source/connection-troubleshooting.txt | 41 +++++++++++++++++++ .../connection/connection-options.txt | 1 + 2 files changed, 42 insertions(+) diff --git a/source/connection-troubleshooting.txt b/source/connection-troubleshooting.txt index 0c8bd3bc8..9a3fc5c36 100644 --- a/source/connection-troubleshooting.txt +++ b/source/connection-troubleshooting.txt @@ -204,6 +204,47 @@ Consider setting ``maxConnectionLifeTime`` and maintains a connection to a MongoDB instance. For more information about these parameters, see :ref:`Connection Pool Settings `. +.. _java-server-selection-errors: + +Server Selection Timeout Exceptions +----------------------------------- + +Your application might not be able to complete a request even when some servers +are available, causing the driver to return a server selection timeout +exception. + +This exception is of type ``MongoTimeoutException``. The following +shows a sample of the exception that occurs if you attempt to send a +request to a replica set in which the primary is not reachable: + +.. code-block:: none + + com.mongodb.MongoTimeoutException: + Timed out while waiting for a server that matches ReadPreferenceServerSelector{readPreference=primary}. + Client view of cluster state is + {type=REPLICA_SET, + servers=[ + {address=localhost:27017, type=UNKNOWN, state=CONNECTING, exception={com.mongodb.MongoSocketOpenException: Exception opening socket}, caused by {java.net.ConnectException: Connection refused}}, + {address=localhost:27018, type=UNKNOWN, state=CONNECTING, exception={com.mongodb.MongoSocketOpenException: Exception opening socket}, caused by {java.net.ConnectException: Connection refused}}, + {address=localhost:27019, type=REPLICA_SET_SECONDARY, roundTripTime=15.0 ms, state=CONNECTED} + ] + } + +The error includes a view of the cluster state that describes the +connection state of each node, which can help you identify the source of +your connection issue. + +In the preceding error, the only connected server, ``localhost:27019``, +is a secondary node. Because of this, the request times out as the +driver is unable to select a server that satisfies the read preference +of ``primary``. In this situation, you can still perform read operations +against the connected secondary node if you set the read preference to +``secondary``, ``secondaryPreferred``, or ``nearest``. + +You can also specify the ``serverSelectionTimeoutMS`` connection option +to adjust the amount of time in which the driver must select a server. To +learn more, see the :ref:`java-connection-options` guide. + .. _java-miscellaneous-errors: Miscellaneous Errors diff --git a/source/fundamentals/connection/connection-options.txt b/source/fundamentals/connection/connection-options.txt index 0ca49b634..7e38b8dcb 100644 --- a/source/fundamentals/connection/connection-options.txt +++ b/source/fundamentals/connection/connection-options.txt @@ -1,3 +1,4 @@ +.. _java-connection-options: .. _connection-options: ================== From b177d0cda135f5af0b4f915e20c05922e36b0b4c Mon Sep 17 00:00:00 2001 From: Nora Reidy Date: Thu, 6 Jun 2024 11:24:00 -0400 Subject: [PATCH 03/37] DOCSP-4079: GridFS write concern (#547) * DOCSP-4079: GridFS write concern * fix * format * tech review (cherry picked from commit 911e639c8d6e2250f02804329d4cffadd3bb07f7) --- source/fundamentals/gridfs.txt | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/source/fundamentals/gridfs.txt b/source/fundamentals/gridfs.txt index 4777e2803..e3ba3d562 100644 --- a/source/fundamentals/gridfs.txt +++ b/source/fundamentals/gridfs.txt @@ -133,6 +133,16 @@ following code snippet: See the `GridFSUploadOptions <{+api+}/apidocs/mongodb-driver-core/com/mongodb/client/gridfs/model/GridFSUploadOptions.html>`__ API Documentation for more information. +.. important:: Use a ``MAJORITY`` Write Concern + + When storing files in a GridFS bucket, ensure that you use the ``WriteConcern.MAJORITY`` + write concern. If you specify a different write concern, replica set elections that occur + during a GridFS file upload might interrupt the upload process and cause some file chunks + to be lost. + + For more information about write concerns, see the :manual:`Write Concern ` + page in the Server manual. + Upload a File Using an Input Stream ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ From 5f7c5cdd3bf42aa5b8cefc654c823840490ad972 Mon Sep 17 00:00:00 2001 From: Rea Rustagi <85902999+rustagir@users.noreply.github.com> Date: Thu, 13 Jun 2024 11:29:13 -0400 Subject: [PATCH 04/37] DOCSP-40400-patch-5.1.1 (#554) (cherry picked from commit ec428ededb3fd5aa973816fcc74afe22a0c756cb) --- snooty.toml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/snooty.toml b/snooty.toml index dc73f4597..d6dc93d9a 100644 --- a/snooty.toml +++ b/snooty.toml @@ -20,7 +20,7 @@ driver = "java" driver-long = "MongoDB Java Driver" driver-short = "Java driver" version = "5.1" -full-version = "{+version+}.0" +full-version = "{+version+}.1" mdb-server = "MongoDB Server" package-name-org = "mongodb-org" api = "https://mongodb.github.io/mongo-java-driver/{+version+}" From ad6fba5b0d3ef948565d57bb61453f89f798fcf2 Mon Sep 17 00:00:00 2001 From: Rea Rustagi <85902999+rustagir@users.noreply.github.com> Date: Fri, 14 Jun 2024 12:52:16 -0400 Subject: [PATCH 05/37] DOCSP-40348: disallow commas in oidc prop val (#553) * DOCSP-40348: disallow commas in oidc prop val * fix * AS PR fixes 1 * MK tech review * MK changes * MK changes (cherry picked from commit fc5ef5ab47d12b7659769fd14eb0c353ea5cf772) --- source/fundamentals/enterprise-auth.txt | 34 ++++++++++++++++++------- 1 file changed, 25 insertions(+), 9 deletions(-) diff --git a/source/fundamentals/enterprise-auth.txt b/source/fundamentals/enterprise-auth.txt index 39b431a64..c937ddc2b 100644 --- a/source/fundamentals/enterprise-auth.txt +++ b/source/fundamentals/enterprise-auth.txt @@ -317,8 +317,9 @@ If your application runs on an Azure VM, or otherwise uses the support. You can specify Azure IMDS OIDC authentication either by -using a ``MongoCredential`` or as part of the connection string. Select the -:guilabel:`Connection String` or :guilabel:`MongoCredential` tab to +using a ``MongoCredential`` or as part of the connection string. + +Select from the :guilabel:`Connection String` or :guilabel:`MongoCredential` tabs to see the corresponding syntax. .. tabs:: @@ -326,8 +327,15 @@ see the corresponding syntax. .. tab:: Connection String :tabid: mongodb-azure-imds-connection-string - Replace the ```` placeholder with the percent-encoded - value of the ``audience`` server parameter configured on your MongoDB deployment. + Replace the ```` placeholder in the + following code with the percent-encoded value of the audience server + parameter configured on your MongoDB deployment. + + The comma (``,``) character and its encoding (``%2C``) are + reserved, and using these characters in a value causes the + driver to interpret commas as delimiters of key-value pairs. + You must specify values that contain commas in a ``MongoCredential`` instance, as + demonstrated in the :guilabel:`MongoCredential` tab. .. code-block:: java @@ -360,7 +368,7 @@ see the corresponding syntax. .. _java-mongodb-oidc-gcp-imds: GCP IMDS -++++++++++ +++++++++ If your application runs on a GCP VM, or otherwise uses the `GCP Instance Metadata Service `__, @@ -368,8 +376,9 @@ you can authenticate to MongoDB by using {+driver-short+}'s built-in GCP support. You can specify GCP IMDS OIDC authentication either by -using a ``MongoCredential`` or as part of the connection string. Select the -:guilabel:`Connection String` or :guilabel:`MongoCredential` tab to +using a ``MongoCredential`` or as part of the connection string. + +Select from the :guilabel:`Connection String` or :guilabel:`MongoCredential` tabs to see the corresponding syntax. .. tabs:: @@ -377,8 +386,15 @@ see the corresponding syntax. .. tab:: Connection String :tabid: mongodb-gcp-imds-connection-string - Replace the ```` placeholder with the percent-encoded - value of the ``audience`` server parameter configured on your MongoDB deployment. + Replace the ```` placeholder in the + following code with the percent-encoded value of the audience server + parameter configured on your MongoDB deployment. + + The comma (``,``) character and its encoding (``%2C``) are + reserved, and using these characters in a value causes the + driver to interpret commas as delimiters of key-value pairs. + You must specify values that contain commas in a ``MongoCredential`` instance, as + demonstrated in the :guilabel:`MongoCredential` tab. .. code-block:: java From b5114e4e72ac8f447309203e640cbe5bb718a794 Mon Sep 17 00:00:00 2001 From: Mike Woofter <108414937+mongoKart@users.noreply.github.com> Date: Fri, 14 Jun 2024 12:19:09 -0500 Subject: [PATCH 06/37] compute engine (#555) (cherry picked from commit 3bc23b316a2b652642e037cae152ab7e2accab85) --- source/fundamentals/enterprise-auth.txt | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/source/fundamentals/enterprise-auth.txt b/source/fundamentals/enterprise-auth.txt index c937ddc2b..24041bfd3 100644 --- a/source/fundamentals/enterprise-auth.txt +++ b/source/fundamentals/enterprise-auth.txt @@ -370,7 +370,7 @@ see the corresponding syntax. GCP IMDS ++++++++ -If your application runs on a GCP VM, or otherwise uses the +If your application runs on a Google Compute Engine VM, or otherwise uses the `GCP Instance Metadata Service `__, you can authenticate to MongoDB by using {+driver-short+}'s built-in GCP support. @@ -459,4 +459,4 @@ named ``"access-token.dat"`` in the local file system: .applyToClusterSettings(builder -> builder.hosts(Arrays.asList(new ServerAddress("", )))) .credential(credential) - .build()); \ No newline at end of file + .build()); From 79133f38b51fff3a822549d158ced0217ade9572 Mon Sep 17 00:00:00 2001 From: Rea Rustagi <85902999+rustagir@users.noreply.github.com> Date: Thu, 20 Jun 2024 10:21:48 -0400 Subject: [PATCH 07/37] DOCSP-40400: whats new for v5.1.1 (#556) * DOCSP-40400: whats new for v5.1.1 * staging (cherry picked from commit 8d73f976ac20d48edc0a4d1aa56b62e149c8e2cd) --- source/whats-new.txt | 18 ++++++++++++++++++ 1 file changed, 18 insertions(+) diff --git a/source/whats-new.txt b/source/whats-new.txt index efe6d220a..db714a236 100644 --- a/source/whats-new.txt +++ b/source/whats-new.txt @@ -19,6 +19,7 @@ What's New Learn what's new in: +* :ref:`Version 5.1.1 ` * :ref:`Version 5.1 ` * :ref:`Version 5.0 ` * :ref:`Version 4.11 ` @@ -36,6 +37,23 @@ Learn what's new in: * :ref:`Version 4.1 ` * :ref:`Version 4.0 ` +.. _java-version-5.1.1: + +What's New in 5.1.1 +------------------- + +The 5.1.1 driver patch includes the following changes: + +- When using the ``MONGODB-OIDC`` authentication mechanism, you must not + include comma characters in the ``authMechanismProperties`` connection + string value. To learn more about this behavior, see the + :ref:`MONGODB-OIDC ` section of the Enterprise + Authentication guide. + +- Optimizes GridFS throughput by removing redundant byte array cloning. + The ``GridFSDownloadStream`` and ``GridFSUploadStream`` types use + the ``BsonDocument`` type instead of ``Document``. + .. _version-5.1: What's New in 5.1 From 59f71edb73129509196c1cf6c37c609b0c0ad9cc Mon Sep 17 00:00:00 2001 From: Nora Reidy Date: Wed, 26 Jun 2024 10:54:19 -0400 Subject: [PATCH 08/37] DOCSP-40887: Fix Connection Troubleshooting note (#558) * DOCSP-40887: Fix Connection Troubleshooting note * edits * MM feedback (cherry picked from commit 7c0f14247146ce9478fc2013ed197217b1d6c937) --- source/connection-troubleshooting.txt | 11 ++++++++++- 1 file changed, 10 insertions(+), 1 deletion(-) diff --git a/source/connection-troubleshooting.txt b/source/connection-troubleshooting.txt index 9a3fc5c36..c3d8c49f2 100644 --- a/source/connection-troubleshooting.txt +++ b/source/connection-troubleshooting.txt @@ -23,7 +23,16 @@ Connection Troubleshooting .. note:: - Test + This page addresses only connection issues. If you encounter other + issues when using MongoDB or the driver, visit the following resources: + + - The :ref:`Issues & Help ` page for + information about reporting bugs, contributing to the driver, and + finding more resources + - The `MongoDB Community Forums <{+communityForums+}>`__ for + questions, discussions, or general technical support + - The :ref:`Frequently Asked Questions (FAQ) ` page for + answers to common questions about the {+driver-short+} .. replacement:: server-selection-timeout-error From ff1bc4eea78f47bbd885b02d6308cd671866deb5 Mon Sep 17 00:00:00 2001 From: Nora Reidy Date: Thu, 27 Jun 2024 10:36:52 -0400 Subject: [PATCH 09/37] DOCSP-18711: Explain BsonRepresentation limitation (#549) * DOCSP-18711: Explain BsonRepresentation limitation * edits * JS feedback * tech review * reduce scroll (cherry picked from commit c4dca6a45fee969386ca2ed8f83b881eaef9b83a) --- .../data-formats/pojo-customization.txt | 58 +++++++++++++- .../code-snippets/LongRepresentableCodec.java | 77 +++++++++++++++++++ 2 files changed, 134 insertions(+), 1 deletion(-) create mode 100644 source/includes/fundamentals/code-snippets/LongRepresentableCodec.java diff --git a/source/fundamentals/data-formats/pojo-customization.txt b/source/fundamentals/data-formats/pojo-customization.txt index 7cfe25cc8..3011dbeba 100644 --- a/source/fundamentals/data-formats/pojo-customization.txt +++ b/source/fundamentals/data-formats/pojo-customization.txt @@ -287,6 +287,10 @@ package: - Specifies the BSON type used to store the value when different from the POJO property. + .. seealso:: + + :ref:`bsonrepresentation-annotation-code-example` + * - ``BsonId`` - Marks a property to serialize as the _id property. @@ -441,6 +445,59 @@ following data: additionalInfo=Document{{dimensions=3x4x5, weight=256g}} ] +.. _bsonrepresentation-annotation-code-example: + +BsonRepresentation Error Example +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The ``@BsonRepresentation`` annotation allows you to store a POJO class field +as a different data type in your MongoDB database. The :ref:`Product POJO +` code example in the :ref:`annotations` section +of this page uses ``@BsonRepresentation`` to store ``String`` values as +``ObjectId`` values in the database documents. + +However, using the ``@BsonRepresentation`` annotation to convert between data types other +than ``String`` and ``ObjectId`` causes the following error message: + +.. code-block:: + :copyable: false + + Codec must implement RepresentationConfigurable to support BsonRepresentation + +For example, the following code adds a ``purchaseDate`` field of type ``Long`` to the +``Product`` POJO. This example attempts to use ``@BsonRepresentation`` to represent ``Long`` +values as ``DateTime`` values in the database: + +.. code-block:: java + :emphasize-lines: 9-10 + + public class Product { + @BsonProperty("modelName") + private String name; + + @BsonId() + @BsonRepresentation(BsonType.OBJECT_ID) + private String serialNumber; + + @BsonRepresentation(BsonType.DATE_TIME) + private Long purchaseDate; + + // ... + } + +The preceding code results in an error. Instead, you can create a custom Codec to +convert the ``purchaseDate`` values from type ``Long`` to ``DateTime``: + +.. literalinclude:: /includes/fundamentals/code-snippets/LongRepresentableCodec.java + :language: java + :start-after: start class + :end-before: end class + +Then, add an instance of the ``LongRepresentableCodec`` to your ``CodecRegistry``, which contains +a mapping between your Codec and the Java object type to which it applies. For instructions +on registering your custom Codec with the ``CodecRegistry``, see the :ref:`fundamentals-codecs` +guide. + .. _pojo-discriminators: Discriminators @@ -699,4 +756,3 @@ codec registry. See the documentation on the :ref:`default codec registry ` For more information about how to register the codecs it includes. - diff --git a/source/includes/fundamentals/code-snippets/LongRepresentableCodec.java b/source/includes/fundamentals/code-snippets/LongRepresentableCodec.java new file mode 100644 index 000000000..51bc2cea9 --- /dev/null +++ b/source/includes/fundamentals/code-snippets/LongRepresentableCodec.java @@ -0,0 +1,77 @@ +package fundamentals; + +import org.bson.BsonInvalidOperationException; +import org.bson.BsonReader; +import org.bson.BsonType; +import org.bson.BsonWriter; +import org.bson.codecs.Codec; +import org.bson.codecs.DecoderContext; +import org.bson.codecs.EncoderContext; +import org.bson.codecs.RepresentationConfigurable; +import org.bson.codecs.configuration.CodecConfigurationException; + + +// start class +public class LongRepresentableCodec implements Codec, RepresentationConfigurable { + private final BsonType representation; + + /** + * Constructs a LongRepresentableCodec with a Int64 representation. + */ + public LongRepresentableCodec() { + representation = BsonType.INT64; + } + + private LongRepresentableCodec(final BsonType representation) { + this.representation = representation; + } + + @Override + public BsonType getRepresentation() { + return representation; + } + + @Override + public Codec withRepresentation(final BsonType representation) { + if (representation != BsonType.INT64 && representation != BsonType.DATE_TIME) { + throw new CodecConfigurationException(representation + + " is not a supported representation for LongRepresentableCodec"); + } + return new LongRepresentableCodec(representation); + } + + + @Override + public void encode(final BsonWriter writer, final Long value, final EncoderContext encoderContext) { + switch (representation) { + case INT64: + writer.writeInt64(value); + break; + case DATE_TIME: + writer.writeDateTime(value); + break; + default: + throw new BsonInvalidOperationException("Cannot encode a Long to a " + + representation); + } + } + + @Override + public Long decode(final BsonReader reader, final DecoderContext decoderContext) { + switch (representation) { + case INT64: + return reader.readInt64(); + case DATE_TIME: + return reader.readDateTime(); + default: + throw new CodecConfigurationException("Cannot decode " + representation + + " to a Long"); + } + } + + @Override + public Class getEncoderClass() { + return Long.class; + } +} +// end class \ No newline at end of file From a5cebbe990c797ed41ee642bc931246c0a581fca Mon Sep 17 00:00:00 2001 From: Rea Rustagi <85902999+rustagir@users.noreply.github.com> Date: Mon, 8 Jul 2024 13:29:23 -0400 Subject: [PATCH 10/37] DOCSP-41030: proxy domain name validation (#559) (cherry picked from commit 83d0c178b529aca2b6bf75eaf3c87172fe386b67) --- source/whats-new.txt | 9 ++++++++- 1 file changed, 8 insertions(+), 1 deletion(-) diff --git a/source/whats-new.txt b/source/whats-new.txt index db714a236..2025ed952 100644 --- a/source/whats-new.txt +++ b/source/whats-new.txt @@ -300,12 +300,20 @@ New features of the 4.11 driver release include: - Support for connecting to MongoDB by using a SOCKS5 proxy. To learn more see :ref:`java-connect-socks`. + +- Fixed an issue related to how domain names are validated when you use proxy + functionality, allowing you to use domain names with more than + six characters in the top-level domain. + - Added the ``getSplitEvent()`` method to the ``ChangeStreamDocument`` class to identify fragments of a change stream event that exceeds 16MB. You must use the aggregation stage ``$changeStreamSplitLargeEvent`` in your change stream to handle events that exceed 16MB. To learn more, see :ref:`java-split-change-stream-events`. + - Added an aggregation stage builder for ``$vectorSearch``. To learn more, see :ref:`Atlas Vector Search `. + - Added Atlas Search index management helpers. To learn more, see :ref:`Atlas Search Indexes `. + - Updated Snappy and Zstd compression library dependency versions. To learn more about the current dependency versions, see :ref:`network-compression`. - Added ``getElapsedTime()`` methods to the following classes to monitor the @@ -331,7 +339,6 @@ New features of the 4.11 driver release include: - `ServerListener <{+api+}/apidocs/mongodb-driver-core/com/mongodb/event/ServerListener.html>`__ - `ServerMonitorListener <{+api+}/apidocs/mongodb-driver-core/com/mongodb/event/ServerMonitorListener.html>`__ - .. _version-4.10: What's New in 4.10 From 89a2afa90741948c81e5145b38be66054e287270 Mon Sep 17 00:00:00 2001 From: Rea Rustagi <85902999+rustagir@users.noreply.github.com> Date: Thu, 11 Jul 2024 12:34:26 -0400 Subject: [PATCH 11/37] DOCSP-41360: v5.1.2 patch release (#560) * DOCSP-41360: v5.1.2 patch release * change full version * remove sig validation item (cherry picked from commit 4d632031833d4ede346982fb3916985435957f04) --- snooty.toml | 2 +- source/whats-new.txt | 32 ++++++++++++++++++++++++++++---- 2 files changed, 29 insertions(+), 5 deletions(-) diff --git a/snooty.toml b/snooty.toml index d6dc93d9a..6b9d3c3b0 100644 --- a/snooty.toml +++ b/snooty.toml @@ -20,7 +20,7 @@ driver = "java" driver-long = "MongoDB Java Driver" driver-short = "Java driver" version = "5.1" -full-version = "{+version+}.1" +full-version = "{+version+}.2" mdb-server = "MongoDB Server" package-name-org = "mongodb-org" api = "https://mongodb.github.io/mongo-java-driver/{+version+}" diff --git a/source/whats-new.txt b/source/whats-new.txt index 2025ed952..1a7f1d515 100644 --- a/source/whats-new.txt +++ b/source/whats-new.txt @@ -19,6 +19,7 @@ What's New Learn what's new in: +* :ref:`Version 5.1.2 ` * :ref:`Version 5.1.1 ` * :ref:`Version 5.1 ` * :ref:`Version 5.0 ` @@ -37,12 +38,27 @@ Learn what's new in: * :ref:`Version 4.1 ` * :ref:`Version 4.0 ` +.. _java-version-5.1.2: + +What's New in 5.1.2 +------------------- + +The 5.1.2 driver patch release includes the following changes: + +- Fixes an issue that prevents the driver from encoding and + decoding concrete classes that extend generic base classes, in cases that you + specify the base class as the generic type of the ``MongoCollection`` instance. + +- Fixes an issue related to how domain names are validated when you use + SOCKS5 proxy functionality, allowing you to use domain names with more than + six characters in the top-level domain. + .. _java-version-5.1.1: What's New in 5.1.1 ------------------- -The 5.1.1 driver patch includes the following changes: +The 5.1.1 driver patch release includes the following changes: - When using the ``MONGODB-OIDC`` authentication mechanism, you must not include comma characters in the ``authMechanismProperties`` connection @@ -178,6 +194,12 @@ The 5.0 driver release introduces the following features: :manual:`listCollections ` Server manual page or :ref:`java-collection-names`. +.. note:: + + The v5.0.2 patch release fixed an issue related to how domain names are validated when you use + SOCKS5 proxy functionality, allowing you to use domain names with more than + six characters in the top-level domain. + .. _version-4.11: What's New in 4.11 @@ -301,9 +323,11 @@ New features of the 4.11 driver release include: - Support for connecting to MongoDB by using a SOCKS5 proxy. To learn more see :ref:`java-connect-socks`. -- Fixed an issue related to how domain names are validated when you use proxy - functionality, allowing you to use domain names with more than - six characters in the top-level domain. +.. note:: + + The v4.11.3 patch release fixed an issue related to how domain names are validated when you use + SOCKS5 proxy functionality, allowing you to use domain names with more than + six characters in the top-level domain. - Added the ``getSplitEvent()`` method to the ``ChangeStreamDocument`` class to identify fragments of a change stream event that exceeds 16MB. You must From 79443d8d1844a7a21055356416cbe547b840418f Mon Sep 17 00:00:00 2001 From: Rea Rustagi <85902999+rustagir@users.noreply.github.com> Date: Fri, 12 Jul 2024 14:19:46 -0400 Subject: [PATCH 12/37] DOCSP-39555: java driver sig verification (#562) (cherry picked from commit 03c9965bcbadbde29b9abfaae571c376f74931bf) --- source/index.txt | 8 +++++++- source/validate-signatures.txt | 3 +++ 2 files changed, 10 insertions(+), 1 deletion(-) create mode 100644 source/validate-signatures.txt diff --git a/source/index.txt b/source/index.txt index 4b535c1ce..831cfcdf8 100644 --- a/source/index.txt +++ b/source/index.txt @@ -30,6 +30,7 @@ MongoDB Java Driver /integrations /compatibility /upgrade + /validate-signatures /legacy View the Source @@ -155,6 +156,12 @@ Learn what changes you might need to make to your application to upgrade driver versions in the :ref:`Upgrade Driver Versions ` section. +Validate Driver Artifact Signatures +----------------------------------- + +Learn about how to validate signatures of {+driver-short+} artifacts +published on Maven in the :ref:`Validate Driver Artifact Signatures ` section. + Migrate from the Legacy API --------------------------- @@ -162,7 +169,6 @@ Learn what changes you might need to make to your application to migrate from the legacy API to the current API in the :ref:`Migrate from the Legacy API ` section. - Learn ------ diff --git a/source/validate-signatures.txt b/source/validate-signatures.txt new file mode 100644 index 000000000..3df0d3f07 --- /dev/null +++ b/source/validate-signatures.txt @@ -0,0 +1,3 @@ +.. _java-validate-signatures: + +.. sharedinclude:: dbx/jvm-validate-artifacts.rst From f66c149f6137da9ff5bf64efe46b705137b58c2d Mon Sep 17 00:00:00 2001 From: Nora Reidy Date: Tue, 16 Jul 2024 09:55:41 -0400 Subject: [PATCH 13/37] DOCSP-40062: BsonProperty getters/setters (#561) * DOCSP-40062: BsonProperty getters/setters * MM feedback (cherry picked from commit 06681df348ccea16baea17d1fae6e7afc0846ba0) --- .../data-formats/pojo-customization.txt | 16 ++++++++++++++-- 1 file changed, 14 insertions(+), 2 deletions(-) diff --git a/source/fundamentals/data-formats/pojo-customization.txt b/source/fundamentals/data-formats/pojo-customization.txt index 3011dbeba..eb79ee05a 100644 --- a/source/fundamentals/data-formats/pojo-customization.txt +++ b/source/fundamentals/data-formats/pojo-customization.txt @@ -303,6 +303,12 @@ package: field to BSON. You can include a discriminator to serialize POJOs nested within the field. + .. important:: + + When applying ``@BsonProperty`` to a private field, you must also add + getter and setter methods for that field to serialize and customize + the field name. + * - ``BsonExtraElements`` - Specifies the POJO field on which to deserialize all elements that are not mapped to a field. The POJO field must be one of the following @@ -348,9 +354,16 @@ several of the preceding annotations. public Product(@BsonProperty("modelName") String name) { this.name = name; } + + public String getName() { + return this.name; + } - // ... + public void setName(String name) { + this.name = name; + } + // ... } .. _bson-annotation-convention: @@ -378,7 +391,6 @@ The annotations in the example POJO specify the following behavior: - Omit the ``relatedItems`` field and value when converting data - Use the ``Product(String name)`` constructor when instantiating the POJO - .. _bsonextraelements-annotation-code-example: BsonExtraElements Example From c0f725b0eedd172bd65a0b9c4bb1a83e5d70505a Mon Sep 17 00:00:00 2001 From: Rea Rustagi <85902999+rustagir@users.noreply.github.com> Date: Tue, 16 Jul 2024 16:35:04 -0400 Subject: [PATCH 14/37] DOCSP-41458: v5.1.3 assertion error (#563) (cherry picked from commit 8eb8069e714c36d714162ad1642f9f03e59e3c8c) --- source/validate-signatures.txt | 2 +- source/whats-new.txt | 10 ++++++++++ 2 files changed, 11 insertions(+), 1 deletion(-) diff --git a/source/validate-signatures.txt b/source/validate-signatures.txt index 3df0d3f07..14fd28ee1 100644 --- a/source/validate-signatures.txt +++ b/source/validate-signatures.txt @@ -1,3 +1,3 @@ .. _java-validate-signatures: -.. sharedinclude:: dbx/jvm-validate-artifacts.rst +.. sharedinclude:: dbx/jvm/validate-artifacts.rst diff --git a/source/whats-new.txt b/source/whats-new.txt index 1a7f1d515..0f95555bd 100644 --- a/source/whats-new.txt +++ b/source/whats-new.txt @@ -19,6 +19,7 @@ What's New Learn what's new in: +* :ref:`Version 5.1.3 ` * :ref:`Version 5.1.2 ` * :ref:`Version 5.1.1 ` * :ref:`Version 5.1 ` @@ -38,6 +39,15 @@ Learn what's new in: * :ref:`Version 4.1 ` * :ref:`Version 4.0 ` +.. _java-version-5.1.3: + +What's New in 5.1.3 +------------------- + +The 5.1.3 driver patch release includes the following changes: + +.. sharedinclude:: dbx/jvm/v5.1.3-wn-items.rst + .. _java-version-5.1.2: What's New in 5.1.2 From 0fc8b1836d90ce1146b7903d6660990127ee06e4 Mon Sep 17 00:00:00 2001 From: Rea Rustagi <85902999+rustagir@users.noreply.github.com> Date: Thu, 18 Jul 2024 11:02:24 -0400 Subject: [PATCH 15/37] DOCSP-41593: typo fix (#565) (cherry picked from commit e5617f8a525c0821872aaade43b15ecc8aeb19f0) --- source/fundamentals/connection/connection-options.txt | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/source/fundamentals/connection/connection-options.txt b/source/fundamentals/connection/connection-options.txt index 7e38b8dcb..9e53569d2 100644 --- a/source/fundamentals/connection/connection-options.txt +++ b/source/fundamentals/connection/connection-options.txt @@ -123,10 +123,10 @@ parameters of the connection URI to specify the behavior of the client. * - **maxIdleTimeMS** - integer - - Specifies the maximum amount of time, in milliseconds, the Java - driver will allow a pooled connection to idle before closing the + - Specifies the maximum amount of time, in milliseconds, that the driver + allows a pooled connection to idle before closing the connection. A value of ``0`` indicates that there is no upper bound - on how long the driver can allow a pooled collection to be idle. + on how long the driver allows a pooled connection to be idle. | **Default**: ``0`` From 10e0b861807a61295d94c712ca917b1ee67b0b1a Mon Sep 17 00:00:00 2001 From: Stephanie <52582720+stephmarie17@users.noreply.github.com> Date: Thu, 18 Jul 2024 09:30:32 -0700 Subject: [PATCH 16/37] DOCSP-40830 Include load balanced mode note (#564) * add note and update links * update for clarity * update link title * add space to link (cherry picked from commit e36cbd82924e2b7dbb9dac0bd3b5cc3343dcb422) --- source/fundamentals/monitoring.txt | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/source/fundamentals/monitoring.txt b/source/fundamentals/monitoring.txt index 8c2fdecbc..33d17e71e 100644 --- a/source/fundamentals/monitoring.txt +++ b/source/fundamentals/monitoring.txt @@ -162,7 +162,7 @@ The driver defines nine SDAM events. The driver divides these nine events between three separate listener interfaces which each listen for three of the nine events. Here are the three interfaces and the events they listen for: -- ``ClusterListener``: :spec:`topology ` +- ``ClusterListener``: :spec:`topology ` related events - ``ServerListener``: events related to ``mongod`` or ``mongos`` processes - ``ServerMonitorListener``: heartbeat related events @@ -172,7 +172,11 @@ implements one of the three preceding interfaces and register an instance of tha class with your ``MongoClient`` instance. For a detailed description of each SDAM event in the driver, see the -:spec:`MongoDB SDAM Logging and Monitoring Specification `. +:spec:`MongoDB SDAM Logging and Monitoring Specification `. + +.. note:: Load Balanced Mode + + The driver doesn't emit heartbeat related events when in load balanced mode. For more details about SDAM events with load balancing, see :spec:`MongoDB Load Balancer Support Specification `. Example ^^^^^^^ From bfec287a4f2b074bb83cdc9d1703f32ce83461ca Mon Sep 17 00:00:00 2001 From: Michael Morisi Date: Mon, 12 Aug 2024 15:33:50 -0400 Subject: [PATCH 17/37] Merge pull request #568 from mcmorisi/DOCSP-42372-username-password DOCSP-42372: Change username and password placeholders --- source/connection-troubleshooting.txt | 6 +++--- source/fundamentals/auth.txt | 6 +++--- .../fundamentals/connection/mongoclientsettings.txt | 2 +- .../fundamentals/connection/network-compression.txt | 2 +- source/fundamentals/connection/tls.txt | 2 +- source/fundamentals/enterprise-auth.txt | 12 ++++++------ source/fundamentals/indexes.txt | 2 +- source/includes/faq/code-snippets/FaqExample.java | 2 +- .../code-snippets/auth-credentials-default.rst | 2 +- .../auth-credentials-gssapi-properties.rst | 2 +- .../auth-credentials-gssapi-subject-key.rst | 2 +- .../auth-credentials-gssapi-ticket-cache.rst | 2 +- .../code-snippets/auth-credentials-gssapi.rst | 2 +- .../code-snippets/auth-credentials-ldap.rst | 2 +- .../code-snippets/auth-credentials-sha1.rst | 2 +- .../code-snippets/auth-credentials-sha256.rst | 2 +- .../quick-reference/QuickReferenceSnippets.java | 2 +- source/quick-start.txt | 2 +- source/usage-examples.txt | 2 +- 19 files changed, 28 insertions(+), 28 deletions(-) diff --git a/source/connection-troubleshooting.txt b/source/connection-troubleshooting.txt index c3d8c49f2..ff913b0f4 100644 --- a/source/connection-troubleshooting.txt +++ b/source/connection-troubleshooting.txt @@ -88,7 +88,7 @@ Connection Troubleshooting .. code-block:: java :copyable: false - String uri = "mongodb://:@:/?authSource=users&authMechanism=SCRAM-SHA-256"; + String uri = "mongodb://:@:/?authSource=users&authMechanism=SCRAM-SHA-256"; MongoClient mongoClient = MongoClients.create(uri); .. replacement:: credentials-provider-alternative-method-description @@ -100,7 +100,7 @@ Connection Troubleshooting .. code-block:: java :copyable: false - MongoCredential credential = MongoCredential.createScramSha256Credential("", "", ""); + MongoCredential credential = MongoCredential.createScramSha256Credential("", "", ""); .. replacement:: authentication-guide-reference @@ -117,7 +117,7 @@ Connection Troubleshooting .. code-block:: java :copyable: false - MongoClient mongoClient = MongoClients.create("mongodb://:@:/?authSource=users"); + MongoClient mongoClient = MongoClients.create("mongodb://:@:/?authSource=users"); .. replacement:: dns-resolution-anchor diff --git a/source/fundamentals/auth.txt b/source/fundamentals/auth.txt index 59e2706a9..0d8630ef4 100644 --- a/source/fundamentals/auth.txt +++ b/source/fundamentals/auth.txt @@ -95,7 +95,7 @@ mechanism: .. code-block:: java - MongoClient mongoClient = MongoClients.create("mongodb://:@:/?authSource="); + MongoClient mongoClient = MongoClients.create("mongodb://:@:/?authSource="); .. tab:: :tabid: MongoCredential @@ -157,7 +157,7 @@ mechanism: .. code-block:: java - MongoClient mongoClient = MongoClients.create("mongodb://:@:/?authSource=&authMechanism=SCRAM-SHA-256"); + MongoClient mongoClient = MongoClients.create("mongodb://:@:/?authSource=&authMechanism=SCRAM-SHA-256"); .. tab:: :tabid: MongoCredential @@ -215,7 +215,7 @@ mechanism: .. code-block:: java - MongoClient mongoClient = MongoClients.create("mongodb://:@:/?authSource=&authMechanism=SCRAM-SHA-1"); + MongoClient mongoClient = MongoClients.create("mongodb://:@:/?authSource=&authMechanism=SCRAM-SHA-1"); .. tab:: :tabid: MongoCredential diff --git a/source/fundamentals/connection/mongoclientsettings.txt b/source/fundamentals/connection/mongoclientsettings.txt index 7bf5fcaf4..4f1ade7ee 100644 --- a/source/fundamentals/connection/mongoclientsettings.txt +++ b/source/fundamentals/connection/mongoclientsettings.txt @@ -187,7 +187,7 @@ This example demonstrates specifying a ``ConnectionString``: :emphasize-lines: 2,4 MongoClient mongoClient = MongoClients.create( - MongoClientSettings.builder().applyConnectionString(new ConnectionString("mongodb+srv://:@:/?connectTimeoutMS=2000")) + MongoClientSettings.builder().applyConnectionString(new ConnectionString("mongodb+srv://:@:/?connectTimeoutMS=2000")) .applyToSocketSettings(builder -> builder.connectTimeout(5L, SECONDS)) .build()); diff --git a/source/fundamentals/connection/network-compression.txt b/source/fundamentals/connection/network-compression.txt index ef319ff22..76390f1e5 100644 --- a/source/fundamentals/connection/network-compression.txt +++ b/source/fundamentals/connection/network-compression.txt @@ -53,7 +53,7 @@ connection string using ``ConnectionString`` or by calling the method in the .. code-block:: java - ConnectionString connectionString = new ConnectionString("mongodb+srv://:@/?compressors=snappy,zlib,zstd"); + ConnectionString connectionString = new ConnectionString("mongodb+srv://:@/?compressors=snappy,zlib,zstd"); MongoClient mongoClient = MongoClients.create(connectionString); Specify compression algorithms using the following strings: diff --git a/source/fundamentals/connection/tls.txt b/source/fundamentals/connection/tls.txt index d826373c2..a84d4ddec 100644 --- a/source/fundamentals/connection/tls.txt +++ b/source/fundamentals/connection/tls.txt @@ -67,7 +67,7 @@ using a method in the ``MongoClientSettings.Builder`` class. .. code-block:: java - MongoClient mongoClient = MongoClients.create("mongodb+srv://:@?tls=true"); + MongoClient mongoClient = MongoClients.create("mongodb+srv://:@?tls=true"); .. tab:: MongoClientSettings :tabid: mongoclientsettings diff --git a/source/fundamentals/enterprise-auth.txt b/source/fundamentals/enterprise-auth.txt index 24041bfd3..f6c15eda0 100644 --- a/source/fundamentals/enterprise-auth.txt +++ b/source/fundamentals/enterprise-auth.txt @@ -92,7 +92,7 @@ mechanism: .. code-block:: java - MongoClient mongoClient = MongoClients.create("@:/?authSource=$external&authMechanism=GSSAPI"); + MongoClient mongoClient = MongoClients.create("@:/?authSource=$external&authMechanism=GSSAPI"); .. tab:: :tabid: MongoCredential @@ -151,7 +151,7 @@ You might need to specify one or more of the following additional .. code-block:: java - MongoClient mongoClient = MongoClients.create("@:/?authSource=$external&authMechanism=GSSAPI&authMechanismProperties=SERVICE_NAME:myService"); + MongoClient mongoClient = MongoClients.create("@:/?authSource=$external&authMechanism=GSSAPI&authMechanismProperties=SERVICE_NAME:myService"); .. tab:: :tabid: MongoCredential @@ -277,7 +277,7 @@ mechanism: .. code-block:: java - MongoClient mongoClient = MongoClients.create(":@:/?authSource=$external&authMechanism=PLAIN"); + MongoClient mongoClient = MongoClients.create(":@:/?authSource=$external&authMechanism=PLAIN"); .. tab:: :tabid: MongoCredential @@ -340,21 +340,21 @@ see the corresponding syntax. .. code-block:: java MongoClient mongoClient = MongoClients.create( - "mongodb://@:/?" + + "mongodb://@:/?" + "?authMechanism=MONGODB-OIDC" + "&authMechanismProperties=ENVIRONMENT:azure,TOKEN_RESOURCE:"); .. tab:: MongoCredential :tabid: mongodb-azure-mongo-credential - Replace the ```` placeholder with the client ID or application ID of the + Replace the ```` placeholder with the client ID or application ID of the Azure managed identity or enterprise application. Replace the ```` placeholder with the value of the ``audience`` server parameter configured on your MongoDB deployment. .. code-block:: java - MongoCredential credential = MongoCredential.createOidcCredential("") + MongoCredential credential = MongoCredential.createOidcCredential("") .withMechanismProperty("ENVIRONMENT", "azure") .withMechanismProperty("TOKEN_RESOURCE", ""); diff --git a/source/fundamentals/indexes.txt b/source/fundamentals/indexes.txt index f05be7497..bce5ff2e5 100644 --- a/source/fundamentals/indexes.txt +++ b/source/fundamentals/indexes.txt @@ -595,4 +595,4 @@ For prior versions of MongoDB, pass "*" as a parameter to your call to For more information about the methods in this section, see the following API Documentation: - `dropIndex() <{+api+}/apidocs/mongodb-driver-sync/com/mongodb/client/MongoCollection.html#dropIndex(java.lang.String)>`__ -- `dropIndexes() <{+api+}/apidocs/mongodb-driver-sync/com/mongodb/client/MongoCollection.html#dropIndexes()>`__ +- `dropIndexes() <{+api+}/apidocs/mongodb-driver-sync/com/mongodb/client/MongoCollection.html#dropIndexes()>`__ \ No newline at end of file diff --git a/source/includes/faq/code-snippets/FaqExample.java b/source/includes/faq/code-snippets/FaqExample.java index 7bc730d7a..ba355e8bc 100644 --- a/source/includes/faq/code-snippets/FaqExample.java +++ b/source/includes/faq/code-snippets/FaqExample.java @@ -34,7 +34,7 @@ public static void main(String[] args) { fromProviders(pojoCodecProvider)); // end myDateAsStringCodec - String uri = "mongodb+srv://:@?retryWrites=true&w=majority"; + String uri = "mongodb+srv://:@?retryWrites=true&w=majority"; try (MongoClient mongoClient = MongoClients.create(uri)) { diff --git a/source/includes/fundamentals/code-snippets/auth-credentials-default.rst b/source/includes/fundamentals/code-snippets/auth-credentials-default.rst index c60212ccd..391bd9153 100644 --- a/source/includes/fundamentals/code-snippets/auth-credentials-default.rst +++ b/source/includes/fundamentals/code-snippets/auth-credentials-default.rst @@ -1,6 +1,6 @@ .. code-block:: java - MongoCredential credential = MongoCredential.createCredential("", "", ""); + MongoCredential credential = MongoCredential.createCredential("", "", ""); MongoClient mongoClient = MongoClients.create( MongoClientSettings.builder() diff --git a/source/includes/fundamentals/code-snippets/auth-credentials-gssapi-properties.rst b/source/includes/fundamentals/code-snippets/auth-credentials-gssapi-properties.rst index 44be88a73..f4ec395ce 100644 --- a/source/includes/fundamentals/code-snippets/auth-credentials-gssapi-properties.rst +++ b/source/includes/fundamentals/code-snippets/auth-credentials-gssapi-properties.rst @@ -1,5 +1,5 @@ .. code-block:: java - MongoCredential credential = MongoCredential.createGSSAPICredential(); + MongoCredential credential = MongoCredential.createGSSAPICredential(); credential = credential.withMechanismProperty(MongoCredential.SERVICE_NAME_KEY, "myService"); diff --git a/source/includes/fundamentals/code-snippets/auth-credentials-gssapi-subject-key.rst b/source/includes/fundamentals/code-snippets/auth-credentials-gssapi-subject-key.rst index 69af1abc0..a5c1da73c 100644 --- a/source/includes/fundamentals/code-snippets/auth-credentials-gssapi-subject-key.rst +++ b/source/includes/fundamentals/code-snippets/auth-credentials-gssapi-subject-key.rst @@ -4,6 +4,6 @@ loginContext.login(); Subject subject = loginContext.getSubject(); - MongoCredential credential = MongoCredential.createGSSAPICredential(); + MongoCredential credential = MongoCredential.createGSSAPICredential(); credential = credential.withMechanismProperty(MongoCredential.JAVA_SUBJECT_KEY, subject); diff --git a/source/includes/fundamentals/code-snippets/auth-credentials-gssapi-ticket-cache.rst b/source/includes/fundamentals/code-snippets/auth-credentials-gssapi-ticket-cache.rst index 2994dee8b..b446e3987 100644 --- a/source/includes/fundamentals/code-snippets/auth-credentials-gssapi-ticket-cache.rst +++ b/source/includes/fundamentals/code-snippets/auth-credentials-gssapi-ticket-cache.rst @@ -3,7 +3,7 @@ /* all MongoClient instances sharing this instance of KerberosSubjectProvider will share a Kerberos ticket cache */ String myLoginContext = "myContext"; - MongoCredential credential = MongoCredential.createGSSAPICredential(); + MongoCredential credential = MongoCredential.createGSSAPICredential(); /* login context defaults to "com.sun.security.jgss.krb5.initiate" if unspecified in KerberosSubjectProvider */ credential = credential.withMechanismProperty(MongoCredential.JAVA_SUBJECT_PROVIDER_KEY, diff --git a/source/includes/fundamentals/code-snippets/auth-credentials-gssapi.rst b/source/includes/fundamentals/code-snippets/auth-credentials-gssapi.rst index 9a78d0853..5f76050a4 100644 --- a/source/includes/fundamentals/code-snippets/auth-credentials-gssapi.rst +++ b/source/includes/fundamentals/code-snippets/auth-credentials-gssapi.rst @@ -1,6 +1,6 @@ .. code-block:: java - MongoCredential credential = MongoCredential.createGSSAPICredential(); + MongoCredential credential = MongoCredential.createGSSAPICredential(); MongoClient mongoClient = MongoClients.create( MongoClientSettings.builder() diff --git a/source/includes/fundamentals/code-snippets/auth-credentials-ldap.rst b/source/includes/fundamentals/code-snippets/auth-credentials-ldap.rst index 305e3201c..d539843dc 100644 --- a/source/includes/fundamentals/code-snippets/auth-credentials-ldap.rst +++ b/source/includes/fundamentals/code-snippets/auth-credentials-ldap.rst @@ -1,6 +1,6 @@ .. code-block:: java - MongoCredential credential = MongoCredential.createPlainCredential(, "$external", ); + MongoCredential credential = MongoCredential.createPlainCredential(, "$external", ); MongoClient mongoClient = MongoClients.create( MongoClientSettings.builder() diff --git a/source/includes/fundamentals/code-snippets/auth-credentials-sha1.rst b/source/includes/fundamentals/code-snippets/auth-credentials-sha1.rst index 29644d77c..c2f382a93 100644 --- a/source/includes/fundamentals/code-snippets/auth-credentials-sha1.rst +++ b/source/includes/fundamentals/code-snippets/auth-credentials-sha1.rst @@ -1,6 +1,6 @@ .. code-block:: java - MongoCredential credential = MongoCredential.createScramSha1Credential("", "", ""); + MongoCredential credential = MongoCredential.createScramSha1Credential("", "", ""); MongoClient mongoClient = MongoClients.create( MongoClientSettings.builder() diff --git a/source/includes/fundamentals/code-snippets/auth-credentials-sha256.rst b/source/includes/fundamentals/code-snippets/auth-credentials-sha256.rst index 2d16a3aa5..02af4fddb 100644 --- a/source/includes/fundamentals/code-snippets/auth-credentials-sha256.rst +++ b/source/includes/fundamentals/code-snippets/auth-credentials-sha256.rst @@ -1,6 +1,6 @@ .. code-block:: java - MongoCredential credential = MongoCredential.createScramSha256Credential("", "", ""); + MongoCredential credential = MongoCredential.createScramSha256Credential("", "", ""); MongoClient mongoClient = MongoClients.create( MongoClientSettings.builder() diff --git a/source/includes/quick-reference/QuickReferenceSnippets.java b/source/includes/quick-reference/QuickReferenceSnippets.java index d58dad57a..90a0c0a98 100644 --- a/source/includes/quick-reference/QuickReferenceSnippets.java +++ b/source/includes/quick-reference/QuickReferenceSnippets.java @@ -171,7 +171,7 @@ private static void searchTextExample(MongoCollection coll) { public static void main(String[] args) { // Replace the uri string with your MongoDB deployment's connection string - String uri = "mongodb+srv://:@?retryWrites=true&w=majority"; + String uri = "mongodb+srv://:@?retryWrites=true&w=majority"; try (MongoClient mongoClient = MongoClients.create(uri)) { MongoDatabase database = mongoClient.getDatabase("movies"); diff --git a/source/quick-start.txt b/source/quick-start.txt index d63082b69..4cac68ca4 100644 --- a/source/quick-start.txt +++ b/source/quick-start.txt @@ -113,7 +113,7 @@ Create a new file ``QuickStartPojoExample.java`` in the same package directory as your ``Movie`` file in your project. Use the following sample code to run a query on your sample dataset in MongoDB Atlas, replacing the value of the ``uri`` variable with your MongoDB Atlas connection string. -Ensure you replace the "" section of the connection string with +Ensure you replace the "" section of the connection string with the password you created for your user that has **atlasAdmin** permissions: .. literalinclude:: /includes/quick-start/code-snippets/QuickStartPojoExample.java diff --git a/source/usage-examples.txt b/source/usage-examples.txt index c24426c69..307fdbf53 100644 --- a/source/usage-examples.txt +++ b/source/usage-examples.txt @@ -66,7 +66,7 @@ to learn how to allow connections to your instance of Atlas and to find the :manual:`connection string ` you use to replace the ``uri`` variable in usage examples. If your instance uses :manual:`SCRAM authentication `, you can replace -```` with your username, ```` with your password, and +```` with your database username, ```` with your database password, and ```` with the IP address or URL of your instance. For more information about connecting to your MongoDB instance, see our From a5cc3ff76aafc42911e3db6bbdbfb774b93534ea Mon Sep 17 00:00:00 2001 From: Rea Rustagi <85902999+rustagir@users.noreply.github.com> Date: Wed, 14 Aug 2024 14:52:44 -0400 Subject: [PATCH 18/37] use share --- source/compatibility.txt | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/source/compatibility.txt b/source/compatibility.txt index 7295fb21e..5007723ea 100644 --- a/source/compatibility.txt +++ b/source/compatibility.txt @@ -42,7 +42,7 @@ The first column lists the driver version. .. sharedinclude:: dbx/compatibility-table-legend.rst -.. include:: /includes/mongodb-compatibility-table-java.rst +.. sharedinclude:: dbx/mongodb-compatibility-table-java.rst Language Compatibility ---------------------- @@ -54,7 +54,7 @@ Java versions. The first column lists the driver version. -.. include:: /includes/language-compatibility-table-java.rst +.. sharedinclude:: dbx/language-compatibility-table-java.rst For more information about how to read the compatibility tables, see our guide on :ref:`MongoDB Compatibility Tables. ` From 4cdbdd83ae9aa820524b070314ff0e4f5b30431a Mon Sep 17 00:00:00 2001 From: Brandon Ly Date: Thu, 29 Aug 2024 13:57:49 -0500 Subject: [PATCH 19/37] Add files via upload --- build.sh | 8 ++++++++ netlify.toml | 9 +++++++++ 2 files changed, 17 insertions(+) create mode 100644 build.sh create mode 100644 netlify.toml diff --git a/build.sh b/build.sh new file mode 100644 index 000000000..b62b6772f --- /dev/null +++ b/build.sh @@ -0,0 +1,8 @@ +# ensures that we always use the latest version of the script +if [ -f build-site.sh ]; then + rm build-site.sh +fi + + +curl https://raw.githubusercontent.com/mongodb/docs-worker-pool/netlify-poc/scripts/build-site.sh -o build-site.sh +sh build-site.sh \ No newline at end of file diff --git a/netlify.toml b/netlify.toml new file mode 100644 index 000000000..2d0a3b987 --- /dev/null +++ b/netlify.toml @@ -0,0 +1,9 @@ +[[integrations]] +name = "snooty-cache-plugin" + +# Production context: all deploys from the Production branch +# set in your site’s Branches settings in the UI will inherit +# these settings. +[build] +publish = "snooty/public" +command = ". ./build.sh" From 4e91f110c180e2d28de37e2a6fdc4b333c3d0a55 Mon Sep 17 00:00:00 2001 From: Rea Rustagi <85902999+rustagir@users.noreply.github.com> Date: Thu, 5 Sep 2024 09:40:37 -0400 Subject: [PATCH 20/37] DOCSP-43284: bump patch to 5.1.4 (#571) (cherry picked from commit 0c17f2e9e29d2c7604e4895c8ac4054c5de463d1) --- snooty.toml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/snooty.toml b/snooty.toml index 6b9d3c3b0..2769c901a 100644 --- a/snooty.toml +++ b/snooty.toml @@ -20,7 +20,7 @@ driver = "java" driver-long = "MongoDB Java Driver" driver-short = "Java driver" version = "5.1" -full-version = "{+version+}.2" +full-version = "{+version+}.4" mdb-server = "MongoDB Server" package-name-org = "mongodb-org" api = "https://mongodb.github.io/mongo-java-driver/{+version+}" From f85ef642f5bce8e0b8098db5eb9713c0e948091a Mon Sep 17 00:00:00 2001 From: Stephanie <52582720+stephmarie17@users.noreply.github.com> Date: Wed, 18 Sep 2024 09:47:08 -0700 Subject: [PATCH 21/37] DOCSP-41762 Add transactions page (#569) add transaction page and code snippet (cherry picked from commit e0ad9544130c4abcf7bb433e99e61e8f79c34ad0) --- source/fundamentals.txt | 1 + source/fundamentals/transactions.txt | 154 ++++++++++++++++++ .../code-snippets/Transaction.java | 42 +++++ 3 files changed, 197 insertions(+) create mode 100644 source/fundamentals/transactions.txt create mode 100644 source/includes/fundamentals/code-snippets/Transaction.java diff --git a/source/fundamentals.txt b/source/fundamentals.txt index 691fcda85..05d6e9b17 100644 --- a/source/fundamentals.txt +++ b/source/fundamentals.txt @@ -20,6 +20,7 @@ Fundamentals /fundamentals/aggregation /fundamentals/aggregation-expression-operations /fundamentals/indexes + /fundamentals/transactions /fundamentals/collations /fundamentals/logging /fundamentals/monitoring diff --git a/source/fundamentals/transactions.txt b/source/fundamentals/transactions.txt new file mode 100644 index 000000000..352b6ad02 --- /dev/null +++ b/source/fundamentals/transactions.txt @@ -0,0 +1,154 @@ +.. _java-fundamentals-transactions: + +============ +Transactions +============ + +.. contents:: On this page + :local: + :backlinks: none + :depth: 2 + :class: singlecol + +.. facet:: + :name: genre + :values: reference + +.. meta:: + :keywords: ACID, write, consistency, code example + +Overview +-------- + +In this guide, you can learn how to use the {+driver-short+} to perform +**transactions**. :manual:`Transactions ` allow +you to run a series of operations that do not change any data until the +transaction is committed. If any operation in the transaction returns an +error, the driver cancels the transaction and discards all data changes +before they ever become visible. + +In MongoDB, transactions run within logical **sessions**. A +:manual:`session ` is a grouping of related +read or write operations that you intend to run sequentially. Sessions +enable :manual:`causal consistency +` for a +group of operations or allow you to execute operations in an +:website:`ACID transaction `. MongoDB +guarantees that the data involved in your transaction operations remains +consistent, even if the operations encounter unexpected errors. + +When using the {+driver-short+}, you can create a new session from a +``MongoClient`` instance as a ``ClientSession`` type. We recommend that you reuse +your client for multiple sessions and transactions instead of +instantiating a new client each time. + +.. warning:: + + Use a ``ClientSession`` only with the ``MongoClient`` (or associated + ``MongoDatabase`` or ``MongoCollection``) that created it. Using a + ``ClientSession`` with a different ``MongoClient`` results in operation + errors. + +.. important:: + + You must include the ``session`` as a parameter for any operations that you + want to include in a transaction. + +Methods +------- + +Create a ``ClientSession`` by using the ``startSession()`` method on your +``MongoClient`` instance. You can then modify the session state by using the +methods provided by the ``ClientSession``. The following table describes the +methods you can use to manage your transaction: + +.. list-table:: + :widths: 25 75 + :header-rows: 1 + + * - Method + - Description + + * - ``startTransaction()`` + - | Starts a new transaction for this session with the + default transaction options. Pass an instance of ``TransactionOptions`` + as a parameter to start a transaction with given options. You + cannot start a transaction if there's already an active transaction + running in the session. + | + | **Parameter**: ``TransactionOptions transactionOptions`` + + * - ``abortTransaction()`` + - | Ends the active transaction for this session. Returns an error + if there is no active transaction for the + session or the transaction was previously ended. + + * - ``commitTransaction()`` + - | Commits the active transaction for this session. Returns an + error if there is no active transaction for the session or if the + transaction was ended. + + * - ``withTransaction()`` + - | Starts a new transaction for this session and runs the given function. This + method handles retries, committing, and aborting transactions. Pass an + instance of ``TransactionBody`` as a parameter that defines the + operations you want to execute within the transaction. + | + | **Parameter**: ``TransactionBody transactionBody`` + +A ``ClientSession`` also has methods to retrieve session properties and modify mutable +session properties. View the :ref:`API +documentation ` to learn more about these methods. + +Example +------- + +The following example demonstrates how you can create a session, create a transaction, +and commit a multi-document insert operation through the following steps: + +1. Create a session from the client by using the ``startSession()`` method. +#. Set transaction options to configure transaction behavior. +#. Use the ``withTransaction()`` method to start a transaction. +#. Insert multiple documents. The ``withTransaction()`` method executes, commits, and aborts + the transaction. If any operation results in errors, ``withTransaction()`` handles canceling + the transaction. + +.. literalinclude:: /includes/fundamentals/code-snippets/Transaction.java + :language: java + :dedent: + :start-after: start transaction + :end-before: end transaction + +If you require more control over your transactions, you can use the ``startTransaction()`` +method. You can use this method with the ``commitTransaction()`` and ``abortTransaction()`` +methods described in the preceding section to manually manage the transaction lifecycle. + +Additional Information +---------------------- + +To learn more about the concepts mentioned in this guide, see the following pages in +the Server manual: + +- :manual:`Transactions ` +- :manual:`Server Sessions ` +- :manual:`Read Isolation, Consistency, and Recency ` + +To learn more about ACID compliance, see the :website:`What are ACID +Properties in Database Management Systems? ` +article on the MongoDB website. + +.. _api-docs-transaction: + +API Documentation +~~~~~~~~~~~~~~~~~ + +To learn more about any of the types or methods discussed in this +guide, see the following API Documentation: + +- `ClientSession <{+api+}/apidocs/mongodb-driver-sync/com/mongodb/client/ClientSession.html>`_ +- `startTransaction <{+api+}/apidocs/mongodb-driver-sync/com/mongodb/client/ClientSession.html#startTransaction()>`_ +- `commitTransaction <{+api+}/apidocs/mongodb-driver-sync/com/mongodb/client/ClientSession.html#commitTransaction()>`_ +- `abortTransaction <{+api+}/apidocs/mongodb-driver-sync/com/mongodb/client/ClientSession.html#abortTransaction()>`_ +- `withTransaction <{+api+}/apidocs/mongodb-driver-sync/com/mongodb/client/ClientSession.html#withTransaction(com.mongodb.client.TransactionBody)>`_ +- `TransactionOptions <{+api+}/apidocs/mongodb-driver-core/com/mongodb/TransactionOptions.html>`_ + \ No newline at end of file diff --git a/source/includes/fundamentals/code-snippets/Transaction.java b/source/includes/fundamentals/code-snippets/Transaction.java new file mode 100644 index 000000000..1756b41dd --- /dev/null +++ b/source/includes/fundamentals/code-snippets/Transaction.java @@ -0,0 +1,42 @@ +package fundamentals; + +// begin imports +import com.mongodb.client.*; +import com.mongodb.client.MongoClient; +import com.mongodb.client.model.WriteConcern; +import org.bson.Document; + +import java.util.Arrays; +// end imports + +public class Transaction { + public static void main(String[] args) { + // start transaction + String connectionString = ""; // Replace with your connection string + try (MongoClient mongoClient = MongoClients.create(connectionString)) { + MongoDatabase database = mongoClient.getDatabase("transaction_db"); + MongoCollection collection = database.getCollection("books"); + + // Sets transaction options + TransactionOptions txnOptions = TransactionOptions.builder() + .writeConcern(WriteConcern.MAJORITY) + .build(); + + try (ClientSession session = mongoClient.startSession()) { + + // Uses withTransaction and lambda for transaction operations + session.withTransaction(() -> { + collection.insertMany(session, Arrays.asList( + new Document("title", "The Bluest Eye").append("author", "Toni Morrison"), + new Document("title", "Sula").append("author", "Toni Morrison"), + new Document("title", "Song of Solomon").append("author", "Toni Morrison") + )); + return null; // Return value as expected by the lambda + }, txnOptions); + } + } catch (Exception e) { + e.printStackTrace(); + } + // end transaction + } +} From 9f2c4df14f0b31fe76964be4105a376cbaa6eaff Mon Sep 17 00:00:00 2001 From: Rea Rustagi <85902999+rustagir@users.noreply.github.com> Date: Wed, 25 Sep 2024 11:13:38 -0400 Subject: [PATCH 22/37] DOCSP-43839: jndi feedback (#573) * DOCSP-43839: jndi feedback * formatting fix * convert to rst include * remove action (cherry picked from commit ad1445a322aedb1b5720a4f0bb9f387469a72101) --- .github/workflows/check-autobuilder.yml | 13 ------------- source/fundamentals/connection/jndi.txt | 5 ++--- .../wildfly-module-with-version.rst | 16 ++++++++++++++++ .../wildfly-module-with-version.xml | 10 ---------- 4 files changed, 18 insertions(+), 26 deletions(-) delete mode 100644 .github/workflows/check-autobuilder.yml create mode 100644 source/includes/fundamentals/code-snippets/wildfly-module-with-version.rst delete mode 100644 source/includes/fundamentals/code-snippets/wildfly-module-with-version.xml diff --git a/.github/workflows/check-autobuilder.yml b/.github/workflows/check-autobuilder.yml deleted file mode 100644 index 8495db969..000000000 --- a/.github/workflows/check-autobuilder.yml +++ /dev/null @@ -1,13 +0,0 @@ -name: Check Autobuilder for Errors - -on: - pull_request: - paths: - - "source/**" - -jobs: - check: - runs-on: ubuntu-latest - steps: - - uses: actions/checkout@v3 - - uses: cbush/snooty-autobuilder-check@main diff --git a/source/fundamentals/connection/jndi.txt b/source/fundamentals/connection/jndi.txt index 56d66da19..c1e863479 100644 --- a/source/fundamentals/connection/jndi.txt +++ b/source/fundamentals/connection/jndi.txt @@ -1,4 +1,5 @@ .. _jndi: +.. _java-sync-jndi: ============================================= Connect to MongoDB by Using a JNDI Datasource @@ -47,9 +48,7 @@ JNDI Datasource. Add the following ``module.xml`` file into the module: - .. literalinclude:: /includes/fundamentals/code-snippets/wildfly-module-with-version.xml - :language: xml - + .. include:: /includes/fundamentals/code-snippets/wildfly-module-with-version.rst #. Add a binding to the naming subsystem configuration that references the preceding module, the ``MongoClientFactory`` class, and the diff --git a/source/includes/fundamentals/code-snippets/wildfly-module-with-version.rst b/source/includes/fundamentals/code-snippets/wildfly-module-with-version.rst new file mode 100644 index 000000000..1a86ee8fb --- /dev/null +++ b/source/includes/fundamentals/code-snippets/wildfly-module-with-version.rst @@ -0,0 +1,16 @@ +.. code-block:: xml + :caption: module.xml + + + + + + + + + + + + + + \ No newline at end of file diff --git a/source/includes/fundamentals/code-snippets/wildfly-module-with-version.xml b/source/includes/fundamentals/code-snippets/wildfly-module-with-version.xml deleted file mode 100644 index b1fd9e6b5..000000000 --- a/source/includes/fundamentals/code-snippets/wildfly-module-with-version.xml +++ /dev/null @@ -1,10 +0,0 @@ - - - - - - - - - - \ No newline at end of file From 58c2d6bc34841e1901d8b933334557158f11f9ea Mon Sep 17 00:00:00 2001 From: rustagir Date: Fri, 27 Sep 2024 11:55:42 -0400 Subject: [PATCH 23/37] encrypt fields embeddings --- snooty.toml | 2 +- source/fundamentals/encrypt-fields.txt | 25 +++++++++++++++++++ .../code-snippets/crypt-gradle-versioned.rst | 5 ++++ .../code-snippets/crypt-maven-versioned.rst | 9 +++++++ 4 files changed, 40 insertions(+), 1 deletion(-) create mode 100644 source/includes/fundamentals/code-snippets/crypt-gradle-versioned.rst create mode 100644 source/includes/fundamentals/code-snippets/crypt-maven-versioned.rst diff --git a/snooty.toml b/snooty.toml index 2769c901a..bf4034de8 100644 --- a/snooty.toml +++ b/snooty.toml @@ -25,7 +25,7 @@ mdb-server = "MongoDB Server" package-name-org = "mongodb-org" api = "https://mongodb.github.io/mongo-java-driver/{+version+}" stable-api = "Stable API" -mongocrypt-version = "1.7.3" +mongocrypt-version = "1.8.0" nettyVersion = "io.netty:netty-all:4.1.87.Final" snappyVersion = "org.xerial.snappy:snappy-java:1.1.10.3" zstdVersion = "com.github.luben:zstd-jni:1.5.5-3" diff --git a/source/fundamentals/encrypt-fields.txt b/source/fundamentals/encrypt-fields.txt index fe8226bac..f26de05cf 100644 --- a/source/fundamentals/encrypt-fields.txt +++ b/source/fundamentals/encrypt-fields.txt @@ -1,3 +1,28 @@ .. _java-fle: .. sharedinclude:: dbx/encrypt-fields.rst + + .. replacement:: driver-specific-content + + .. important:: Compatible Encryption Library Version + + The {+driver-short+} uses the `mongodb-crypt + `__ + encryption library for in-use encryption. This driver version + is compatible with ``mongodb-crypt`` v{+mongocrypt-version+}. + + Select from the following :guilabel:`Maven` and + :guilabel:`Gradle` tabs to see how to add the ``mongodb-crypt`` + dependency to your project by using the specified manager: + + .. tabs:: + + .. tab:: Maven + :tabid: maven-dependency + + .. include:: /includes/fundamentals/code-snippets/crypt-maven-versioned.rst + + .. tab:: Gradle + :tabid: gradle-dependency + + .. include:: /includes/fundamentals/code-snippets/crypt-gradle-versioned.rst \ No newline at end of file diff --git a/source/includes/fundamentals/code-snippets/crypt-gradle-versioned.rst b/source/includes/fundamentals/code-snippets/crypt-gradle-versioned.rst new file mode 100644 index 000000000..2bb77055b --- /dev/null +++ b/source/includes/fundamentals/code-snippets/crypt-gradle-versioned.rst @@ -0,0 +1,5 @@ +.. code-block:: groovy + + dependencies { + implementation 'org.mongodb:mongodb-crypt:{+mongocrypt-version+}' + } \ No newline at end of file diff --git a/source/includes/fundamentals/code-snippets/crypt-maven-versioned.rst b/source/includes/fundamentals/code-snippets/crypt-maven-versioned.rst new file mode 100644 index 000000000..0b2c3b0e4 --- /dev/null +++ b/source/includes/fundamentals/code-snippets/crypt-maven-versioned.rst @@ -0,0 +1,9 @@ +.. code-block:: xml + + + + org.mongodb + mongodb-crypt + {+mongocrypt-version+} + + From ded9499d4d042cd2adc96a6b109fb62bfbe498ba Mon Sep 17 00:00:00 2001 From: Jordan Smith <45415425+jordan-smith721@users.noreply.github.com> Date: Fri, 11 Oct 2024 07:59:29 -0700 Subject: [PATCH 24/37] Update troubleshooting guidance (#576) (cherry picked from commit f0b3abf7df3b137b602a8cff0eb93c8576d5a46f) --- source/connection-troubleshooting.txt | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/source/connection-troubleshooting.txt b/source/connection-troubleshooting.txt index ff913b0f4..b05ba4ce5 100644 --- a/source/connection-troubleshooting.txt +++ b/source/connection-troubleshooting.txt @@ -269,8 +269,10 @@ Monitor Thread Exception INFO: Exception in monitor thread while connecting to server ssc-cluster-01-shard-00-02.9cbnp.mongodb.net:27017 -To resolve this error, you must install certificates as described under -:ref:`Security Certificate Errors `. +This log line indicates that the monitor that continuously +checks the status of each replica set member or ``mongos`` server failed to +contact one of the nodes or servers. This is an expected message during server +maintenance operations and can be safely ignored. Certificate Request Exception ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ From 4868ce6d0dd83a386b531bf73e64d1560120016f Mon Sep 17 00:00:00 2001 From: Rea Rustagi <85902999+rustagir@users.noreply.github.com> Date: Tue, 15 Oct 2024 10:57:05 -0400 Subject: [PATCH 25/37] DOCSP-44292: add back compat + link in I&H (#578) * DOCSP-44292: add back compat + link in I&H * MW PR fixes 1 (cherry picked from commit 6311ead90b3f4323f142682ee54a6004169a85d7) --- source/issues-and-help.txt | 47 ++++++++++++++++++++++++-------------- 1 file changed, 30 insertions(+), 17 deletions(-) diff --git a/source/issues-and-help.txt b/source/issues-and-help.txt index 99e734008..e2a8e327b 100644 --- a/source/issues-and-help.txt +++ b/source/issues-and-help.txt @@ -4,7 +4,12 @@ Issues & Help ============= -.. default-domain:: mongodb +.. facet:: + :name: genre + :values: reference + +.. meta:: + :keywords: java sync, troubleshooting, feedback .. contents:: On this page :local: @@ -13,28 +18,37 @@ Issues & Help :class: singlecol We are lucky to have a vibrant MongoDB Java community that includes users -with varying levels of experience using the Java driver. We find the quickest -way to get support for general questions is through the `MongoDB Community Forums `_. - -Refer to our `support channels `_ -documentation for more information. +with varying levels of experience using the {+driver-short+}. The +quickest way to get support for general questions is through the +:community-forum:`MongoDB Community Forums `. Bugs / Feature Requests ----------------------- -If you think you've found a bug or want to see a new feature in the Java -driver, please open a case in our issue management tool, JIRA: +If you have feedback about the {+driver-short+}, visit the `MongoDB +Feedback Engine `__ and select +:guilabel:`Drivers` from the list of products on the right side of +your screen. You can propose improvements, report issues, and provide +other types of feedback by using this site. + +You can also open a case in Jira, our issue management tool, to identify +bugs or propose improvements. The following steps describe how to create +a Jira issue: -* `Create an account and login `_. -* Navigate to `the JAVA project `_. -* Click :guilabel:`Create`. Please provide as much information as possible - about the issue and the steps to reproduce it. +1. Visit the `MongoDB Jira issue tracker `__ and click the + `signup link. `__ + Create an account, and then log in to Jira. +#. Navigate to the `JAVA Jira project. `__ +#. Click :guilabel:`Create` to create a ticket. Please provide as much + information as possible about the issue or request in the ticket. -Bug reports in JIRA for the Java driver and the Core Server (SERVER) project are **public**. +.. note:: -If you’ve identified a security vulnerability in a driver or any other -MongoDB project, please report it according to the instructions found in the -:manual:`Create a Vulnerability Report page `. + Bug reports in the JAVA Jira project are publicly viewable. + +If you’ve identified a security vulnerability in any official MongoDB +product, please report it according to the instructions found in the +:manual:`Create a Vulnerability Report page. ` Pull Requests ------------- @@ -57,4 +71,3 @@ Finally, ensure that the code passes gradle checks. .. code-block:: bash $ ./gradlew check - From bcde2e510da95fe2bca813748a2038e9e880dc64 Mon Sep 17 00:00:00 2001 From: Elyse Foreman Date: Mon, 21 Oct 2024 11:23:12 -0400 Subject: [PATCH 26/37] (DOCSP-44283) Removed EOL'd v4.9 (#580) (#582) --- source/whats-new.txt | 352 +------------------------------------------ 1 file changed, 1 insertion(+), 351 deletions(-) diff --git a/source/whats-new.txt b/source/whats-new.txt index 0f95555bd..569db101a 100644 --- a/source/whats-new.txt +++ b/source/whats-new.txt @@ -26,18 +26,6 @@ Learn what's new in: * :ref:`Version 5.0 ` * :ref:`Version 4.11 ` * :ref:`Version 4.10 ` -* :ref:`Version 4.9 ` -* :ref:`Version 4.8 ` -* :ref:`Version 4.7.1 ` -* :ref:`Version 4.7.0 ` -* :ref:`Version 4.6 ` -* :ref:`Version 4.5.1 ` -* :ref:`Version 4.5 ` -* :ref:`Version 4.4 ` -* :ref:`Version 4.3 ` -* :ref:`Version 4.2 ` -* :ref:`Version 4.1 ` -* :ref:`Version 4.0 ` .. _java-version-5.1.3: @@ -397,342 +385,4 @@ New features of the 4.10 driver release include: - Support for :ref:`qe-manual-feature-qe` (QE). To learn more about the requirements for using the QE feature, see the :ref:`Queryable Encryption Driver Compatibility Table - `. - -.. _version-4.9: - -What's New in 4.9 ------------------ - -.. important:: Aggregation Expression Operations Are in Beta - - This driver version introduces an API for creating - :ref:`aggregation expressions `. - This feature is in beta phase. - -New features of the 4.9 driver release include: - -- Added a new exception to identify when a constructor annotated by - ``BsonCreator`` contains parameters with annotations other than - ``BsonProperty`` or ``BsonId``. -- Changed the log message format for command monitoring messages reported - by the ``org.mongodb.driver.protocol.command`` package. -- Added support for the ``$documents`` aggregation pipeline stage to the - `Aggregates <{+api+}/apidocs/mongodb-driver-core/com/mongodb/client/model/Aggregates#documents(java.util.List)>`__ - helper class. -- Added `MongoClientSettings.Builder.applyToLoggerSettings() <{+api+}/apidocs/mongodb-driver-core/com/mongodb/MongoClientSettings.Builder.html#applyToLoggerSettings(com.mongodb.Block)>`__ - and `LoggerSettings.Builder.maxDocumentLength() <{+api+}/apidocs/mongodb-driver-core/com/mongodb/LoggerSettings.Builder.html#maxDocumentLength(int)>`__ - methods that let you specify a maximum length for the extended JSON representation of a - BSON document in a log message. - -.. _version-4.8: - -What's New in 4.8 ------------------ - -.. warning:: Breaking Changes in v4.8 - - The v4.8 driver contains breaking changes. See :ref:`` - and :ref:`` for more information. - -.. important:: Deprecation Notice - - The ``MapCodec`` and ``IterableCodec`` classes are deprecated. - Instead of ``MapCodec``, use ``MapCodecProvider``. Instead of ``IterableCodec``, - use ``CollectionCodecProvider``, or ``IterableCodecProvider`` for ``Iterable`` - types that aren't ``Collection`` types. - -Behavioral changes with the 4.8 driver release include: - -- Requirement that you 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. -- Logging of new connection messages at the ``DEBUG`` level instead - of at ``INFO``. - -New features of the 4.8 driver release include: - -- Support for authentication with AWS. The driver takes an - optional dependency on both AWS SDK version 1 and version 2. -- Support for obtaining credentials from the environment for both GCP - and Azure for in-use encryption. -- Support for deserialization of records containing components with - generic parameters. -- Support for deserialization of records containing components with more - specific container types, such as ``SortedSet``, ``NavigableMap``, ``LinkedList``, - or ``TreeSet``. -- Support for recursive record types, records whose type - definitions contain cycles. -- Inclusion of the ``disambiguatedPaths`` field in change stream update events - when the ``showExpandedEvents`` server feature is enabled on MongoDB v6.1 - and later. Learn more about this field from the `getDisambiguatedPaths() `__ - API documentation. Learn more about the ``showExpandedEvents`` setting from - the :manual:`Expanded Events ` - server documentation. - -.. _version-4.7.1: -.. _version-4.7: - -What's New in 4.7.1 -------------------- - -The 4.7.1 driver patches a bug that affects -Client-Side Field Level Encryption and Queryable Encryption. -The bug can cause data corruption when rotating :ref:`Data Encryption Keys ` -(DEKs) encrypted with a :ref:`Customer Master Key ` -hosted on Google Cloud Key Management Service or Azure -Key Vault. The bug was present in version 4.7.0 of the driver -in the ``RewrapManyDataKey`` method and causes the -loss of your DEKs. - -.. important:: Back Up your Key Vault Collection - - Always back up your :ref:`Key Vault Collection ` - before you rotate your DEKs. If you lose your DEKs, you lose access to all - the data encrypted with those keys. - -.. _version-4.7.0: - -What's New in 4.7 ------------------ - -.. warning:: Breaking Changes in v4.7 - - The v4.7 driver contains breaking changes. See :ref:`` - for more information. - -New features of the 4.7 driver release include: - -- Added full support for MongoDB 6.0. - -- Added the following change stream support improvements: - - - Enhanced pre-image and post-image support for :ref:`change streams `. - Change stream watch helpers now accept ``whenAvailable`` and ``required`` - for the ``fullDocument`` option. See the :manual:`change stream ` - reference documentation for more information. - - Added a new ``fullDocumentBeforeChange`` option, which accepts - ``whenAvailable`` and ``required``. - - Change events now include a ``fullDocumentBeforeChange`` field - when configured for display on your MongoDB collection. - - Added ``showExpandedEvents`` support for change streams. - - Added ``wallTime`` support to the ``ChangeStreamDocument`` class. - -- Added :ref:`clustered index ` creation support. -- Support for new features related to :ref:`qe-manual-feature-qe`, - including support for automatic encryption (MongoDB v6.0 Enterprise or later - is required) and manual encryption. - - - Support for the new Queryable Encryption shared library, which removes the need - for the ``mongocryptd`` process. The queryable encryption shared library requires - `org.mongodb:mongodb-crypt `__ - version ``1.5.1.1`` or later. - -- Added a new API for encryption key management. - -- Added builder API methods for more aggregation stages - including :pipeline:`$search`/:pipeline:`$searchMeta` (Atlas only), - :pipeline:`$densify`, and :pipeline:`$fill`. Learn more about these - methods on the :ref:`Aggregates Builder ` page. - -- Added the ``BsonExtraElements`` annotation that can be used with POJO encoding - and decoding. ``BsonExtraElements`` enables decoding objects that might receive - new fields in the future without requiring developers to explicitly map - those new fields. - -- Performance optimizations including: - - - Lock-free implementations of the server session pool and the buffer pool. - - A new cleanup implementation of ``DBCursor`` that uses Java's - Cleaner API instead of finalization, available in Java 9 or later. - -- The :ref:`setWindowFields ` builder API - is no longer a beta feature. Changes in the API break both binary and source - compatibility. See :ref:`` for more information. - -.. _version-4.6: - -What's New in 4.6 ------------------ - -New features of the 4.6 Java driver release include: - -- The buffer pool is now shared across all ``MongoClient`` instances. The - buffer pool prunes buffers that have been idle for one minute. -- Added an API to specify suppliers for AWS KMS credentials for - Client-Side Field Level Encryption (CSFLE). See the - `AutoEncryptionSettings.Builder.kmsProviderPropertySuppliers() `__ - and the `ClientEncryptionSettings.Builder.kmsProviderPropertySuppliers() `__ - API documentation for more information. -- Added compatibility to ``org.mongodb:mongodb-crypt``, a dependency for - CSFLE, for Apple M1 ARM-based hardware. -- Added a service provider interface (SPI) to allow the driver to specify - a custom DNS client. See the `DnsClient `__ - and the `DnsClientProvider `__ - interface API documentation for more information. -- Added driver support for encoding and decoding between `Java records `__ - and BSON documents, which is enabled by default. See :ref:`` - for more information. - -.. _version-4.5: -.. _version-4.5.1: - -What's New in 4.5.1 -------------------- - -If the DNS server returns an NXDomain error, -indicating a non-existent domain, the 4.5.1 -driver no longer throws an exception. - -.. _version-4.5.0: - -What's New in 4.5 ------------------ - -New features of the 4.5 Java driver release include: - -- Added support for specifying custom service names of SRV resource - records. See the ``srvServiceName`` setting in the :ref:`Connection - Options ` guide for more information. -- Added support to customize UUID representation in a codec registry using - the ``CodecRegistries.withUuidRepresentation()`` method. -- Added support for overriding listener settings in ``ClusterSettings``, - ``ServerSettings`` and ``ConnectionPoolSettings`` builders. -- All events received by ``ClusterListener``, ``ServerListener``, and - ``ServerMonitorListener`` are now totally ordered using - a happens-before relationship when the listeners are not shared by - different MongoClient instances. To learn more about the happens-before - ordering, see `Happens-before Order `__ - in the Java Language Specification. -- Added ``EnumCodec`` and ``EnumCodecProvider`` classes to separate codec - support for ``enum`` types from the ``PojoCodec`` class. The default - codec registries, which you can access from the ``MongoClientSettings`` and the ``Bson`` - interfaces, now include the ``enum`` codec classes. If your application uses - a custom enumeration codec and one of the default registries, ensure - you order them as described in the section on :ref:`overriding codecs `. -- Resolved performance issues that impacted versions 4.4 and 4.3 of the - driver. Performance in this version is similar to performance in 4.2. -- Resolved an issue in which errors originating from retrieving the cluster - description weren't passed to the ``onError`` Subscriber callback -- Resolved an issue with releasing ``ByteBuf`` instances when you connect - with compression enabled. -- Removed an unnecessary dependency on the ``javax.annotation.*`` packages - from the ``org.mongodb.driver-core`` OSGi bundle. - -.. _version-4.4: - -What's New in 4.4 ------------------ - -New features of the 4.4 Java driver release include: - -- Compatibility with MongoDB 5.1 and support for Java 17 -- Added support for index hints in an ``AggregateIterable`` -- Added support for the ``$merge`` and ``$out`` aggregation stages on secondaries -- Use of the ``mergeObjects()`` method in the ``Updates`` builder -- ``DocumentCodec`` does not ignore a :ref:`CodecRegistry ` when writing to an ``Iterable`` or a ``Map`` instance - -.. _version-4.3: - -What's New in 4.3 ------------------ - -New features of the 4.3 Java driver release include: - -- Added support for the MongoDB {+stable-api+}. For more information, see our - :ref:`{+stable-api+} guide `. - - .. note:: - - Starting from February 2022, the **Versioned API** is known the - **{+stable-api+}**. All concepts and features remain the same with this - naming change. - -- Added support for connection to - `MongoDB Atlas Serverless Instances `__. - For more information about setup, see our documentation on how to - :atlas:`Create a New Serverless Instance ` -- Added a builder API for the ``setWindowFields`` pipeline stage to allow the use of window operators -- Added support for setting Netty `io.netty.handler.ssl.SslContext `__ -- Added support for snapshot reads to ``ClientSession`` -- Limited the rate of establishing new connections per connection pool -- Removed most restrictions on allowed characters in the field names of documents you insert or replace. This is a behavioral change for any application that is relying on client-side enforcement of these restrictions. - -The following table shows the restriction status on allowed characters -in the field names of documents: - -.. list-table:: - :header-rows: 1 - :stub-columns: 1 - :widths: 15 25 60 - - * - Character - - Operation - - Description - - * - **.** - - Insert and Replace - - Removed restrictions on field names containing this character. - - * - **$** - - Insert - - Removed restrictions on field names starting with this character. - - * - **$** - - Replace - - Removed restrictions in nested documents on field names containing this character. - - * - **$** - - Replace - - Kept restrictions in top-level documents on field names starting with this character. This prevents accidental use of a replace operation when the intention was to use an update operation. - -.. note:: - - Unacknowledged writes using dollar-prefixed or dotted keys might - be silently rejected by pre-5.0 servers, where some restrictions on - field names are still enforced in the server. - -.. _version-4.2: - -What's New in 4.2 ------------------ - -.. warning:: Breaking Changes in v4.2 - - The v4.2 driver contains breaking changes. See :ref:`` - for more information. - -New features of the 4.2 Java driver release include: - -- Added Azure and GCP key stores to client-side field level encryption -- Added Kerberos caching tickets for reuse in multiple authentication requests -- Added `MongoClients `_ instances with ``MongoClientSettings`` or ``ConnectionString`` as the configuration -- Use of the ``explain()`` method on `find `_ and `aggregate `_ commands -- Added a `JsonObject `_ class to make encoding from and decoding to JSON more efficient by avoiding an intermediate Map representation -- Added a `BsonRepresentation `_ annotation that allows you to represent the ``ObjectId`` BSON values as a ``String`` in `POJO `_ classes -- Added a `Filters.empty() `_ method - -.. _version-4.1: - -What's New in 4.1 ------------------ - -New features of the 4.1 Java driver release include: - -- Significant reduction in client-perceived failover times during planned maintenance events -- The `update() `_ and `delete() `_ methods now support index hints -- The ``find()`` method supports `allowDiskUse() `_ for sorts that require too much memory to execute in RAM -- Added support for the MONGODB-AWS authentication mechanism using Amazon Web Services (AWS) Identity and Access Management (IAM) credentials -- Authentication requires fewer round trips to the server, resulting in faster connection setup - -.. _version-4.0: - -What's New in 4.0 ------------------ - -.. warning:: Breaking Changes in v4.0 - - The v4.0 driver contains breaking changes. See :ref:`` - for more information. - -This release adds no new features. + `. \ No newline at end of file From ffe51a0187231d54ea1fdc2a8fb219cde53143f4 Mon Sep 17 00:00:00 2001 From: Caitlin Davey Date: Wed, 23 Oct 2024 14:09:28 -0400 Subject: [PATCH 27/37] DOCSP-42961: Removed Nested Components (#581) * DOCSP-42961: Removed Nested Components * Fixing indentation errors * Fixing indentation errors again * Fixing indentation errors again * Fixing indentation errors again * Fixing indentation errors again+ * Fixing indentation errors again+ * Fixing code block indentation * tweaks based on internal review feedback * tweaks based on internal review feedback - indentation issues * tweaks based on internal review feedback - indentation issues * tweaks based on internal review feedback - indentation issues * tweaks based on internal review feedback - indentation issues * tweaks to bullet issue * tweaks to bullet issue (cherry picked from commit 1ec4a2cb37e86ae27541064eadc448302a665678) --- .../connection/mongoclientsettings.txt | 35 ++++++++-------- .../data-formats/pojo-customization.txt | 40 ++++++++----------- 2 files changed, 32 insertions(+), 43 deletions(-) diff --git a/source/fundamentals/connection/mongoclientsettings.txt b/source/fundamentals/connection/mongoclientsettings.txt index 4f1ade7ee..154cec5c6 100644 --- a/source/fundamentals/connection/mongoclientsettings.txt +++ b/source/fundamentals/connection/mongoclientsettings.txt @@ -259,26 +259,23 @@ settings to modify the driver's behavior: * - ``serverSelector()`` - Adds a server selector to apply before server selection. - + * - ``srvHost()`` - - Sets the host name to use to look up an SRV DNS record to find the - MongoDB hosts. - - .. note:: - - When setting ``srvHost``, the driver does not process any - associated TXT records associated with the host. - - If you want to enable the processing of TXT records, you must - specify the SRV host in the connection string using the - ``applyConnectionString()`` method. - - .. code-block:: java - :emphasize-lines: 3 - - MongoClient mongoClient = MongoClients.create( - MongoClientSettings.builder() - .applyConnectionString(new ConnectionString("mongodb+srv://host1.acme.com"))) + - | Sets the host name to use to look up an SRV DNS record to find the + MongoDB hosts. + | + | If you want to enable the processing of TXT records associated with the host, + specify the SRV host in the connection string + using the ``applyConnectionString()`` method. + | + | For example: + + .. code-block:: java + :emphasize-lines: 3 + + MongoClient mongoClient = + MongoClients.create(MongoClientSettings.builder() + .applyConnectionString(new ConnectionString("mongodb+srv://host1.acme.com"))) * - ``srvMaxHosts()`` - | Sets the maximum number of hosts the driver can connect to when using diff --git a/source/fundamentals/data-formats/pojo-customization.txt b/source/fundamentals/data-formats/pojo-customization.txt index eb79ee05a..ea54ddce4 100644 --- a/source/fundamentals/data-formats/pojo-customization.txt +++ b/source/fundamentals/data-formats/pojo-customization.txt @@ -285,11 +285,7 @@ package: * - ``BsonRepresentation`` - Specifies the BSON type used to store the value when different from the - POJO property. - - .. seealso:: - - :ref:`bsonrepresentation-annotation-code-example` + POJO property. See an example of :ref:`bsonrepresentation-annotation-code-example` on this page. * - ``BsonId`` - Marks a property to serialize as the _id property. @@ -299,28 +295,24 @@ package: and/or deserialize a property. * - ``BsonProperty`` - - Specifies a custom document field name when converting the POJO - field to BSON. You can include a discriminator to serialize POJOs - nested within the field. - - .. important:: + - | Specifies a custom document field name when converting the POJO + field to BSON. You can include a discriminator to serialize POJOs + nested within the field. + | + | When applying ``@BsonProperty`` to a private field, + **you must also add getter and setter methods for that field to serialize and + customize the field name**. - When applying ``@BsonProperty`` to a private field, you must also add - getter and setter methods for that field to serialize and customize - the field name. * - ``BsonExtraElements`` - - Specifies the POJO field on which to deserialize all elements that are - not mapped to a field. The POJO field must be one of the following - types: - - - `Document <{+api+}/apidocs/bson/org/bson/Document.html>`__ - - `BsonDocument <{+api+}/apidocs/bson/org/bson/BsonDocument.html>`__ - - ``Map`` - - .. seealso:: - - :ref:`BsonExtraElements Annotation Example ` + - | Specifies the POJO field on which to deserialize all elements that are + not mapped to a field. The POJO field must be one of the following + types: + | - `Document <{+api+}/apidocs/bson/org/bson/Document.html>`__ + | - `BsonDocument <{+api+}/apidocs/bson/org/bson/BsonDocument.html>`__ + | - ``Map`` + | + | See an example of a :ref:`BsonExtraElements Annotation Example `. The following code snippet shows a sample POJO called ``Product`` that uses several of the preceding annotations. From 1033e754d0aae127984500892a8e8891a4ca8429 Mon Sep 17 00:00:00 2001 From: lindseymoore <71525840+lindseymoore@users.noreply.github.com> Date: Mon, 25 Nov 2024 16:36:47 -0500 Subject: [PATCH 28/37] [Backport v5.1] DOCSP-44901 Shorten TOC (#594) * [Backport v5.2] DOCSP-44901 TOC Relabel (#593) * delete 'one/many' changes (cherry picked from commit b9819b038374a00a1de3705568e1f9b555321a55) * DOCSP-44901 TOC Relabel (cherry picked from commit c08fb6cac465dafdda42d874613803dcd066cb6d) * remaining changes * add back page bullets (cherry picked from commit 418963b1c794628f1f854d4631edd867c364fcd3) * include backport --- .github/workflows/backport.yml | 26 ++++++++++++++ source/fundamentals.txt | 36 +++++++++---------- source/fundamentals/builders.txt | 12 +++---- source/fundamentals/connection.txt | 16 ++++----- source/fundamentals/crud.txt | 8 ++--- source/fundamentals/crud/read-operations.txt | 26 +++++++------- source/fundamentals/crud/write-operations.txt | 20 +++++------ source/fundamentals/data-formats.txt | 24 ++++++------- source/index.txt | 26 +++++++------- source/usage-examples.txt | 19 +++++----- source/usage-examples/delete-operations.txt | 11 +++--- source/usage-examples/find-operations.txt | 10 +++--- source/usage-examples/insert-operations.txt | 10 +++--- source/usage-examples/update-operations.txt | 14 ++++---- 14 files changed, 140 insertions(+), 118 deletions(-) create mode 100644 .github/workflows/backport.yml diff --git a/.github/workflows/backport.yml b/.github/workflows/backport.yml new file mode 100644 index 000000000..971e8a650 --- /dev/null +++ b/.github/workflows/backport.yml @@ -0,0 +1,26 @@ +name: Backport +on: + pull_request_target: + types: + - closed + - labeled + +jobs: + backport: + name: Backport + runs-on: ubuntu-latest + # Only react to merged PRs for security reasons. + # See https://docs.github.com/en/actions/using-workflows/events-that-trigger-workflows#pull_request_target. + if: > + github.event.pull_request.merged + && ( + github.event.action == 'closed' + || ( + github.event.action == 'labeled' + && contains(github.event.label.name, 'backport') + ) + ) + steps: + - uses: tibdex/backport@v2 + with: + github_token: ${{ secrets.GITHUB_TOKEN }} \ No newline at end of file diff --git a/source/fundamentals.txt b/source/fundamentals.txt index 05d6e9b17..019c88bd7 100644 --- a/source/fundamentals.txt +++ b/source/fundamentals.txt @@ -9,23 +9,23 @@ Fundamentals :titlesonly: :maxdepth: 1 - /fundamentals/connection - /fundamentals/auth - /fundamentals/enterprise-auth - /fundamentals/stable-api - /fundamentals/databases-collections - /fundamentals/data-formats - /fundamentals/crud - /fundamentals/builders - /fundamentals/aggregation - /fundamentals/aggregation-expression-operations - /fundamentals/indexes - /fundamentals/transactions - /fundamentals/collations - /fundamentals/logging - /fundamentals/monitoring - /fundamentals/gridfs - /fundamentals/encrypt-fields - /fundamentals/time-series + Connection Guide + Authentication + Enterprise Authentication + Stable API + Databases & Collections + Data Formats + CRUD Operations + Builders + Aggregation + Aggregation Expressions + Indexes + Transactions + Collations + Logging + Monitoring + GridFS + In-Use Encryption + Time Series Collections .. include:: /includes/fundamentals-sections.rst diff --git a/source/fundamentals/builders.txt b/source/fundamentals/builders.txt index 631622fa8..ee1e92425 100644 --- a/source/fundamentals/builders.txt +++ b/source/fundamentals/builders.txt @@ -8,12 +8,12 @@ Builders .. toctree:: - /fundamentals/builders/aggregates - /fundamentals/builders/filters - /fundamentals/builders/indexes - /fundamentals/builders/projections - /fundamentals/builders/sort - /fundamentals/builders/updates + Aggregation + Filters + Indexes + Projection + Sort + Update .. contents:: On this page :local: diff --git a/source/fundamentals/connection.txt b/source/fundamentals/connection.txt index 6f398ba7d..63969b0f1 100644 --- a/source/fundamentals/connection.txt +++ b/source/fundamentals/connection.txt @@ -6,14 +6,14 @@ Connection Guide .. toctree:: - /fundamentals/connection/connect - /fundamentals/connection/connection-options - /fundamentals/connection/mongoclientsettings - /fundamentals/connection/network-compression - /fundamentals/connection/tls - /fundamentals/connection/socks - /fundamentals/connection/jndi - Connect to MongoDB Atlas from AWS Lambda + Connect to MongoDB + Connection Options + MongoClient Settings + Network Compression + TLS/SSL + SOCKS5 Proxy + JNDI Datasource + AWS Lambda .. contents:: On this page :local: diff --git a/source/fundamentals/crud.txt b/source/fundamentals/crud.txt index 262ab9d41..3417cd5e0 100644 --- a/source/fundamentals/crud.txt +++ b/source/fundamentals/crud.txt @@ -9,10 +9,10 @@ CRUD Operations .. toctree:: :caption: CRUD Operations - /fundamentals/crud/read-operations - /fundamentals/crud/write-operations - /fundamentals/crud/query-document - /fundamentals/crud/compound-operations + Read + Write + Query + Compound Operations CRUD (Create, Read, Update, Delete) operations enable you to work with data stored in MongoDB. diff --git a/source/fundamentals/crud/read-operations.txt b/source/fundamentals/crud/read-operations.txt index f0c264f90..0eb147951 100644 --- a/source/fundamentals/crud/read-operations.txt +++ b/source/fundamentals/crud/read-operations.txt @@ -5,6 +5,19 @@ Read Operations .. meta:: :description: Learn about the commands for running read operations on MongoDB by using the {+driver-long+}. +.. toctree:: + :caption: Read Operations + + Retrieve Data + Data from a Cursor + Open Change Streams + Sort Results + Skip Returned Results + Limit Returned Results + Specify Fields to Return + Geospatial Data + Search Text + - :doc:`/fundamentals/crud/read-operations/retrieve` - :doc:`/fundamentals/crud/read-operations/cursor` - :doc:`/fundamentals/crud/read-operations/change-streams` @@ -14,16 +27,3 @@ Read Operations - :doc:`/fundamentals/crud/read-operations/project` - :doc:`/fundamentals/crud/read-operations/geo` - :doc:`/fundamentals/crud/read-operations/text` - -.. toctree:: - :caption: Read Operations - - /fundamentals/crud/read-operations/retrieve - /fundamentals/crud/read-operations/cursor - /fundamentals/crud/read-operations/change-streams - /fundamentals/crud/read-operations/sort - /fundamentals/crud/read-operations/skip - /fundamentals/crud/read-operations/limit - /fundamentals/crud/read-operations/project - /fundamentals/crud/read-operations/geo - /fundamentals/crud/read-operations/text diff --git a/source/fundamentals/crud/write-operations.txt b/source/fundamentals/crud/write-operations.txt index f9ca6ec47..fd4e57d6a 100644 --- a/source/fundamentals/crud/write-operations.txt +++ b/source/fundamentals/crud/write-operations.txt @@ -5,19 +5,19 @@ Write Operations .. meta:: :description: Learn about the commands for running MongoDB write operations by using the {+driver-long+}. +.. toctree:: + :caption: Write Operations + + Insert + Delete + Modify + Update Array Elements + Upsert + Bulk Operations + - :doc:`/fundamentals/crud/write-operations/insert` - :doc:`/fundamentals/crud/write-operations/delete` - :doc:`/fundamentals/crud/write-operations/modify` - :doc:`/fundamentals/crud/write-operations/embedded-arrays` - :doc:`/fundamentals/crud/write-operations/upsert` - :doc:`/fundamentals/crud/write-operations/bulk` - -.. toctree:: - :caption: Write Operations - - /fundamentals/crud/write-operations/insert - /fundamentals/crud/write-operations/delete - /fundamentals/crud/write-operations/modify - /fundamentals/crud/write-operations/embedded-arrays - /fundamentals/crud/write-operations/upsert - /fundamentals/crud/write-operations/bulk diff --git a/source/fundamentals/data-formats.txt b/source/fundamentals/data-formats.txt index 280b95ab4..a26dfd099 100644 --- a/source/fundamentals/data-formats.txt +++ b/source/fundamentals/data-formats.txt @@ -5,6 +5,17 @@ Data Formats .. meta:: :description: Learn how to convert between MongoDB and Java data formats by using the {+driver-long+}. +.. toctree:: + :caption: Data Formats + + BSON + Extended JSON + Documents + POJOs + Records + POJO Customization + Codecs + - :doc:`/fundamentals/data-formats/document-data-format-bson` - :doc:`/fundamentals/data-formats/document-data-format-extended-json` - :doc:`/fundamentals/data-formats/documents` @@ -12,16 +23,3 @@ Data Formats - :doc:`/fundamentals/data-formats/document-data-format-record` - :doc:`/fundamentals/data-formats/pojo-customization` - :doc:`/fundamentals/data-formats/codecs` - -.. toctree:: - :caption: Data Formats - - /fundamentals/data-formats/document-data-format-bson - /fundamentals/data-formats/document-data-format-extended-json - /fundamentals/data-formats/documents - /fundamentals/data-formats/document-data-format-pojo - /fundamentals/data-formats/document-data-format-record - /fundamentals/data-formats/pojo-customization - /fundamentals/data-formats/codecs - - diff --git a/source/index.txt b/source/index.txt index 831cfcdf8..5399663d5 100644 --- a/source/index.txt +++ b/source/index.txt @@ -19,19 +19,19 @@ MongoDB Java Driver :maxdepth: 1 Quick Start - /quick-reference - /whats-new - /usage-examples - /fundamentals - /api-documentation - /faq - /connection-troubleshooting - /issues-and-help - /integrations - /compatibility - /upgrade - /validate-signatures - /legacy + Quick Reference + What's New + Usage Examples + Fundamentals + API Documentation + FAQ + Connection Troubleshooting + Issues & Help + Driver Integrations + Compatibility + Upgrade + Validate Driver Signatures + Migrate from the Legacy API View the Source Introduction diff --git a/source/usage-examples.txt b/source/usage-examples.txt index 307fdbf53..208b025ec 100644 --- a/source/usage-examples.txt +++ b/source/usage-examples.txt @@ -12,16 +12,15 @@ Usage Examples .. toctree:: - /usage-examples/find-operations - /usage-examples/insert-operations - /usage-examples/update-operations - /usage-examples/delete-operations - /usage-examples/bulkWrite - /usage-examples/watch - /usage-examples/count - /usage-examples/distinct - /usage-examples/command - + Find + Insert + Update & Replace + Delete + Bulk Operations + Watch for Changes + Count Documents + Distinct Field Values + Run a Command Overview -------- diff --git a/source/usage-examples/delete-operations.txt b/source/usage-examples/delete-operations.txt index f458f84e4..811d30db6 100644 --- a/source/usage-examples/delete-operations.txt +++ b/source/usage-examples/delete-operations.txt @@ -5,12 +5,11 @@ Delete Operations .. meta:: :description: Learn by example: how to delete data from MongoDB by using the {+driver-long+}. -- :doc:`Delete a Document ` -- :doc:`Delete Multiple Documents ` - .. toctree:: :caption: Examples - /usage-examples/deleteOne - /usage-examples/deleteMany - + Delete One + Delete Many + +- :doc:`Delete a Document ` +- :doc:`Delete Multiple Documents ` diff --git a/source/usage-examples/find-operations.txt b/source/usage-examples/find-operations.txt index 37c2dc28e..712144c6d 100644 --- a/source/usage-examples/find-operations.txt +++ b/source/usage-examples/find-operations.txt @@ -5,11 +5,11 @@ Find Operations .. meta:: :description: Learn by example: how to create queries and retrieve data from MongoDB by using the {+driver-long+}. -- :doc:`Find a Document ` -- :doc:`Find Multiple Documents ` - .. toctree:: :caption: Examples - /usage-examples/findOne - /usage-examples/find + Find One + Find Many + +- :doc:`Find a Document ` +- :doc:`Find Multiple Documents ` diff --git a/source/usage-examples/insert-operations.txt b/source/usage-examples/insert-operations.txt index 77951e3e2..0c4b9975e 100644 --- a/source/usage-examples/insert-operations.txt +++ b/source/usage-examples/insert-operations.txt @@ -5,11 +5,11 @@ Insert Operations .. meta:: :description: Learn by example: how to insert data into MongoDB by using the {+driver-long+}. -- :doc:`Insert a Document ` -- :doc:`Insert Multiple Documents ` - .. toctree:: :caption: Examples - /usage-examples/insertOne - /usage-examples/insertMany + Insert One + Insert Many + +- :doc:`Insert a Document ` +- :doc:`Insert Multiple Documents ` diff --git a/source/usage-examples/update-operations.txt b/source/usage-examples/update-operations.txt index d09625d7f..0f8e93d37 100644 --- a/source/usage-examples/update-operations.txt +++ b/source/usage-examples/update-operations.txt @@ -5,13 +5,13 @@ Update & Replace Operations .. meta:: :description: Learn by example: how to update and replace data in MongoDB by using the {+driver-long+}. -- :doc:`Update a Document ` -- :doc:`Update Multiple Documents ` -- :doc:`Replace a Document ` - .. toctree:: :caption: Examples - /usage-examples/updateOne - /usage-examples/updateMany - /usage-examples/replaceOne + Update One + Update Many + Replace One + +- :doc:`Update a Document ` +- :doc:`Update Multiple Documents ` +- :doc:`Replace a Document ` From d4073ffce6ac0321839e27a402fc81b20e5d014e Mon Sep 17 00:00:00 2001 From: "github-actions[bot]" <41898282+github-actions[bot]@users.noreply.github.com> Date: Wed, 27 Nov 2024 15:41:13 -0600 Subject: [PATCH 29/37] clarify build tools (#598) (#600) (cherry picked from commit 773bbf3014cad0aa161102dadd829e18810e72d0) --- source/quick-start.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/quick-start.txt b/source/quick-start.txt index 4cac68ca4..1aeb7ab4e 100644 --- a/source/quick-start.txt +++ b/source/quick-start.txt @@ -52,7 +52,7 @@ If you are using `Gradle `__, add the following to your .. note:: - We recommend that you use a build tool to install the + We recommend that you use a build tool, such as Maven or Gradle, to install the {+driver-short+}. However, if you must download the driver and dependencies, you can find the JAR files in the `MongoDB Group Maven repository `__. From 46785f48b73baa20e0fb7fb244ac3465426aedb5 Mon Sep 17 00:00:00 2001 From: Michael Morisi Date: Mon, 2 Dec 2024 10:17:01 -0500 Subject: [PATCH 30/37] Merge pull request #604 from mcmorisi/DOCSP-45726-reduce-width DOCSP-45726: Reduce width of Document code samples --- .../fundamentals/data-formats/documents.txt | 54 +++++++++++++------ 1 file changed, 38 insertions(+), 16 deletions(-) diff --git a/source/fundamentals/data-formats/documents.txt b/source/fundamentals/data-formats/documents.txt index 5fe6a98aa..58e9146e9 100644 --- a/source/fundamentals/data-formats/documents.txt +++ b/source/fundamentals/data-formats/documents.txt @@ -116,11 +116,15 @@ different field types: Document author = new Document("_id", new ObjectId()) .append("name", "Gabriel García Márquez") - .append("dateOfDeath", Date.from(LocalDate.of(2014, 4, 17).atStartOfDay(ZoneId.systemDefault()).toInstant())) + .append("dateOfDeath", + Date.from(LocalDate.of(2014, 4, 17).atStartOfDay(ZoneId.systemDefault()).toInstant())) .append("novels", Arrays.asList( - new Document("title", "One Hundred Years of Solitude").append("yearPublished", 1967), - new Document("title", "Chronicle of a Death Foretold").append("yearPublished", 1981), - new Document("title", "Love in the Time of Cholera").append("yearPublished", 1985))); + new Document("title", "One Hundred Years of Solitude") + .append("yearPublished", 1967), + new Document("title", "Chronicle of a Death Foretold") + .append("yearPublished", 1981), + new Document("title", "Love in the Time of Cholera") + .append("yearPublished", 1985))); To insert this document into a collection, instantiate a collection using the ``getCollection()`` method and call the :doc:`insertOne @@ -228,11 +232,16 @@ different field types: BsonDocument author = new BsonDocument() .append("_id", new BsonObjectId()) .append("name", new BsonString("Gabriel García Márquez")) - .append("dateOfDeath", new BsonDateTime(LocalDate.of(2014, 4, 17).atStartOfDay(ZoneId.systemDefault()).toInstant().toEpochMilli())) + .append("dateOfDeath", + new BsonDateTime(LocalDate.of(2014, 4, 17).atStartOfDay(ZoneId.systemDefault()) + .toInstant().toEpochMilli())) .append("novels", new BsonArray(Arrays.asList( - new BsonDocument().append("title", new BsonString("One Hundred Years of Solitude")).append("yearPublished", new BsonInt32(1967)), - new BsonDocument().append("title", new BsonString("Chronicle of a Death Foretold")).append("yearPublished", new BsonInt32(1981)), - new BsonDocument().append("title", new BsonString("Love in the Time of Cholera")).append("yearPublished", new BsonInt32(1985)) + new BsonDocument().append("title", new BsonString("One Hundred Years of Solitude")) + .append("yearPublished", new BsonInt32(1967)), + new BsonDocument().append("title", new BsonString("Chronicle of a Death Foretold")) + .append("yearPublished", new BsonInt32(1981)), + new BsonDocument().append("title", new BsonString("Love in the Time of Cholera")) + .append("yearPublished", new BsonInt32(1985)) ))); To insert this document into a collection, instantiate a collection @@ -359,7 +368,11 @@ The output of the preceding code resembles the following: .. code-block:: none :copyable: false - query result in extended json format: {"_id": {"$oid": "6035210f35bd203721c3eab8"}, "name": "Gabriel García Márquez", "dateOfDeath": {"$date": "2014-04-17T04:00:00Z"}, "novels": [{"title": "One Hundred Years of Solitude", "yearPublished": 1967}, {"title": "Chronicle of a Death Foretold", "yearPublished": 1981}, {"title": "Love in the Time of Cholera", "yearPublished": 1985}]} + query result in extended json format: {"_id": {"$oid": "6035210f35bd203721c3eab8"}, + "name": "Gabriel García Márquez", "dateOfDeath": {"$date": "2014-04-17T04:00:00Z"}, + "novels": [{"title": "One Hundred Years of Solitude", "yearPublished": 1967}, + {"title": "Chronicle of a Death Foretold", "yearPublished": 1981}, + {"title": "Love in the Time of Cholera", "yearPublished": 1985}]} .. tip:: @@ -394,7 +407,8 @@ The output of the preceding code resembles the following: JsonObject author = new JsonObject("{\"_id\": \"6035210f35bd203721c3eab8\", " + "\"name\": \"Gabriel García Márquez\", " + "\"dateOfDeath\": {\"$date\": \"2014-04-17T04:00:00Z\"}, " - + "\"novels\": [{\"title\": \"One Hundred Years of Solitude\", \"yearPublished\": 1967}, {\"title\": \"Chronicle of a Death Foretold\", \"yearPublished\": 1981}, " + + "\"novels\": [{\"title\": \"One Hundred Years of Solitude\", \"yearPublished\": 1967}, + {\"title\": \"Chronicle of a Death Foretold\", \"yearPublished\": 1981}, " + "{\"title\": \"Love in the Time of Cholera\", \"yearPublished\": 1985}]}\n"); collection.insertOne(author); JsonObject query = new JsonObject("{\"name\": \"Gabriel Garc\\u00eda M\\u00e1rquez\"}"); @@ -408,7 +422,10 @@ The output of the preceding code resembles the following: .. code-block:: none :copyable: false - query result in relaxed json format: {"_id": "6035210f35bd203721c3eab8", "name": "Gabriel García Márquez", "dateOfDeath": {"$date": "2014-04-17T04:00:00Z"}, "novels": [{"title": "One Hundred Years of Solitude", "yearPublished": 1967}, {"title": "Chronicle of a Death Foretold", "yearPublished": 1981}, {"title": "Love in the Time of Cholera", "yearPublished": 1985}]} + query result in relaxed json format: {"_id": "6035210f35bd203721c3eab8", "name": "Gabriel García Márquez", + "dateOfDeath": {"$date": "2014-04-17T04:00:00Z"}, "novels": [{"title": "One Hundred Years of Solitude", + "yearPublished": 1967}, {"title": "Chronicle of a Death Foretold", "yearPublished": 1981}, + {"title": "Love in the Time of Cholera", "yearPublished": 1985}]} For more information about the methods and classes mentioned in this section, see the following API Documentation: @@ -442,11 +459,15 @@ different field types: BasicDBObject author = new BasicDBObject("_id", new ObjectId()) .append("name", "Gabriel García Márquez") - .append("dateOfDeath", Date.from(LocalDate.of(2014, 4, 17).atStartOfDay(ZoneId.systemDefault()).toInstant())) + .append("dateOfDeath", Date.from(LocalDate.of(2014, 4, 17) + .atStartOfDay(ZoneId.systemDefault()).toInstant())) .append("novels", Arrays.asList( - new BasicDBObject("title", "One Hundred Years of Solitude").append("yearPublished", 1967), - new BasicDBObject("title", "Chronicle of a Death Foretold").append("yearPublished", 1981), - new BasicDBObject("title", "Love in the Time of Cholera").append("yearPublished", 1985))); + new BasicDBObject("title", "One Hundred Years of Solitude") + .append("yearPublished", 1967), + new BasicDBObject("title", "Chronicle of a Death Foretold") + .append("yearPublished", 1981), + new BasicDBObject("title", "Love in the Time of Cholera") + .append("yearPublished", 1985))); To insert this document into a collection, instantiate a collection using the ``getCollection()`` method specifying the ``BasicDBObject`` class as @@ -470,7 +491,8 @@ data from the collection using the following code: import com.mongodb.client.model.Filters; // - BasicDBObject doc = collection.find(Filters.eq("name", "Gabriel García Márquez")).first(); + BasicDBObject doc = + collection.find(Filters.eq("name", "Gabriel García Márquez")).first(); if (doc != null) { System.out.println("_id: " + doc.getObjectId("_id") + ", name: " + doc.getString("name") From dfae7794eaadd4cf0fe73060347d5b02c033c94a Mon Sep 17 00:00:00 2001 From: Jordan Smith <45415425+jordan-smith721@users.noreply.github.com> Date: Mon, 16 Dec 2024 07:12:15 -0800 Subject: [PATCH 31/37] Fix codec code bug (#605) (cherry picked from commit 88c396a6abb51757d6481ab917fa90f623a52cfe) --- source/fundamentals/data-formats/codecs.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/fundamentals/data-formats/codecs.txt b/source/fundamentals/data-formats/codecs.txt index ecb4ea416..786532da7 100644 --- a/source/fundamentals/data-formats/codecs.txt +++ b/source/fundamentals/data-formats/codecs.txt @@ -176,7 +176,7 @@ from the prior example using the following code: .. code-block:: java :copyable: true - Codec powerStatusCodec = codecRegistry.get(String.class); + Codec powerStatusCodec = codecRegistry.get(PowerStatus.class); Codec integerCodec = codecRegistry.get(Integer.class); If you attempt to retrieve a ``Codec`` instance for a class that is not From 2a262e6277dba887d0d5161b293352288ba604fb Mon Sep 17 00:00:00 2001 From: Rachel Mackintosh <148898879+rachel-mack@users.noreply.github.com> Date: Mon, 24 Mar 2025 12:20:32 -0400 Subject: [PATCH 32/37] Backport 655 to v5.1 (#660) * [Java Sync] P1 - Shift Java ToC (#615) * fix redirects (#616) * [Java Sync] P2 - Shift Java ToC (#617) * toc-tweaks * redirects * reference * toc * databases adn collections * reference links * rm reference landing --- config/redirects | 60 +++++++++- snooty.toml | 12 +- source/{fundamentals => }/aggregation.txt | 6 + .../aggregation-expression-operations.txt | 0 source/atlas-search.txt | 21 ++++ source/atlas-vector-search.txt | 107 ++++++++++++++++++ source/{fundamentals => }/builders.txt | 12 +- .../builders/aggregates.txt | 6 +- .../{fundamentals => }/builders/filters.txt | 2 +- .../{fundamentals => }/builders/indexes.txt | 2 +- .../builders/projections.txt | 2 +- source/{fundamentals => }/builders/sort.txt | 6 +- .../{fundamentals => }/builders/updates.txt | 0 source/{usage-examples => }/command.txt | 0 source/{fundamentals => }/connection.txt | 14 +-- .../{fundamentals => }/connection/connect.txt | 4 +- .../connection/connection-options.txt | 2 +- .../connection-troubleshooting.txt | 7 -- source/{fundamentals => }/connection/jndi.txt | 0 .../connection/mongoclientsettings.txt | 0 .../connection/network-compression.txt | 0 .../stable-api.txt | 0 source/crud.txt | 28 +++++ source/{fundamentals => crud}/collations.txt | 0 .../crud/compound-operations.txt | 12 +- source/{fundamentals => crud}/gridfs.txt | 17 ++- .../crud/query-document.txt | 0 source/crud/read-operations.txt | 29 +++++ .../crud/read-operations/cursor.txt | 0 .../crud/read-operations/geo.txt | 8 +- .../crud/read-operations/limit.txt | 2 +- .../crud/read-operations/project.txt | 0 .../crud/read-operations/retrieve.txt | 4 +- .../crud/read-operations/skip.txt | 0 .../crud/read-operations/sort.txt | 8 +- .../crud/read-operations/text.txt | 2 +- .../{fundamentals => crud}/transactions.txt | 0 source/crud/write-operations.txt | 25 ++++ .../crud/write-operations/bulk.txt | 0 .../crud/write-operations/delete.txt | 0 .../crud/write-operations/embedded-arrays.txt | 2 +- .../crud/write-operations/insert.txt | 2 +- .../crud/write-operations/modify.txt | 4 +- .../crud/write-operations/upsert.txt | 0 source/data-formats.txt | 26 +++++ .../data-formats/codecs.txt | 0 .../document-data-format-bson.txt | 0 .../document-data-format-extended-json.txt | 0 .../document-data-format-pojo.txt | 0 .../document-data-format-record.txt | 0 .../data-formats/documents.txt | 0 .../data-formats/pojo-customization.txt | 0 .../time-series.txt | 2 +- .../databases-collections.txt | 0 source/fundamentals.txt | 31 ----- source/fundamentals/crud.txt | 27 ----- source/fundamentals/crud/read-operations.txt | 29 ----- source/fundamentals/crud/write-operations.txt | 23 ---- source/fundamentals/data-formats.txt | 25 ---- .../{quick-start.txt => getting-started.txt} | 16 ++- .../{ => getting-started}/quick-reference.txt | 0 source/index.txt | 35 +++--- source/{fundamentals => }/indexes.txt | 0 source/integrations.txt | 6 +- source/logging-monitoring.txt | 14 +++ .../change-streams.txt | 0 .../logging.txt | 2 +- .../monitoring.txt | 2 +- source/reference.txt | 15 +++ source/{ => reference}/compatibility.txt | 0 source/{ => reference}/legacy.txt | 0 source/{ => reference}/upgrade.txt | 0 source/{ => reference}/whats-new.txt | 0 source/security.txt | 17 +++ source/{fundamentals => security}/auth.txt | 2 +- .../encrypt-fields.txt | 0 .../enterprise-auth.txt | 0 .../connection => security}/socks.txt | 0 .../connection => security}/tls.txt | 0 source/{ => security}/validate-signatures.txt | 0 source/usage-examples.txt | 2 +- source/usage-examples/find.txt | 6 +- source/usage-examples/findOne.txt | 6 +- source/usage-examples/updateMany.txt | 2 +- source/usage-examples/updateOne.txt | 2 +- 85 files changed, 457 insertions(+), 239 deletions(-) rename source/{fundamentals => }/aggregation.txt (98%) rename source/{fundamentals => aggregation}/aggregation-expression-operations.txt (100%) create mode 100644 source/atlas-search.txt create mode 100644 source/atlas-vector-search.txt rename source/{fundamentals => }/builders.txt (91%) rename source/{fundamentals => }/builders/aggregates.txt (99%) rename source/{fundamentals => }/builders/filters.txt (99%) rename source/{fundamentals => }/builders/indexes.txt (98%) rename source/{fundamentals => }/builders/projections.txt (99%) rename source/{fundamentals => }/builders/sort.txt (97%) rename source/{fundamentals => }/builders/updates.txt (100%) rename source/{usage-examples => }/command.txt (100%) rename source/{fundamentals => }/connection.txt (73%) rename source/{fundamentals => }/connection/connect.txt (97%) rename source/{fundamentals => }/connection/connection-options.txt (99%) rename source/{ => connection}/connection-troubleshooting.txt (97%) rename source/{fundamentals => }/connection/jndi.txt (100%) rename source/{fundamentals => }/connection/mongoclientsettings.txt (100%) rename source/{fundamentals => }/connection/network-compression.txt (100%) rename source/{fundamentals => connection}/stable-api.txt (100%) create mode 100644 source/crud.txt rename source/{fundamentals => crud}/collations.txt (100%) rename source/{fundamentals => }/crud/compound-operations.txt (96%) rename source/{fundamentals => crud}/gridfs.txt (97%) rename source/{fundamentals => }/crud/query-document.txt (100%) create mode 100644 source/crud/read-operations.txt rename source/{fundamentals => }/crud/read-operations/cursor.txt (100%) rename source/{fundamentals => }/crud/read-operations/geo.txt (97%) rename source/{fundamentals => }/crud/read-operations/limit.txt (98%) rename source/{fundamentals => }/crud/read-operations/project.txt (100%) rename source/{fundamentals => }/crud/read-operations/retrieve.txt (98%) rename source/{fundamentals => }/crud/read-operations/skip.txt (100%) rename source/{fundamentals => }/crud/read-operations/sort.txt (98%) rename source/{fundamentals => }/crud/read-operations/text.txt (99%) rename source/{fundamentals => crud}/transactions.txt (100%) create mode 100644 source/crud/write-operations.txt rename source/{fundamentals => }/crud/write-operations/bulk.txt (100%) rename source/{fundamentals => }/crud/write-operations/delete.txt (100%) rename source/{fundamentals => }/crud/write-operations/embedded-arrays.txt (98%) rename source/{fundamentals => }/crud/write-operations/insert.txt (98%) rename source/{fundamentals => }/crud/write-operations/modify.txt (97%) rename source/{fundamentals => }/crud/write-operations/upsert.txt (100%) create mode 100644 source/data-formats.txt rename source/{fundamentals => }/data-formats/codecs.txt (100%) rename source/{fundamentals => }/data-formats/document-data-format-bson.txt (100%) rename source/{fundamentals => }/data-formats/document-data-format-extended-json.txt (100%) rename source/{fundamentals => }/data-formats/document-data-format-pojo.txt (100%) rename source/{fundamentals => }/data-formats/document-data-format-record.txt (100%) rename source/{fundamentals => }/data-formats/documents.txt (100%) rename source/{fundamentals => }/data-formats/pojo-customization.txt (100%) rename source/{fundamentals => data-formats}/time-series.txt (97%) rename source/{fundamentals => }/databases-collections.txt (100%) delete mode 100644 source/fundamentals.txt delete mode 100644 source/fundamentals/crud.txt delete mode 100644 source/fundamentals/crud/read-operations.txt delete mode 100644 source/fundamentals/crud/write-operations.txt delete mode 100644 source/fundamentals/data-formats.txt rename source/{quick-start.txt => getting-started.txt} (92%) rename source/{ => getting-started}/quick-reference.txt (100%) rename source/{fundamentals => }/indexes.txt (100%) create mode 100644 source/logging-monitoring.txt rename source/{fundamentals/crud/read-operations => logging-monitoring}/change-streams.txt (100%) rename source/{fundamentals => logging-monitoring}/logging.txt (99%) rename source/{fundamentals => logging-monitoring}/monitoring.txt (99%) create mode 100644 source/reference.txt rename source/{ => reference}/compatibility.txt (100%) rename source/{ => reference}/legacy.txt (100%) rename source/{ => reference}/upgrade.txt (100%) rename source/{ => reference}/whats-new.txt (100%) create mode 100644 source/security.txt rename source/{fundamentals => security}/auth.txt (99%) rename source/{fundamentals => security}/encrypt-fields.txt (100%) rename source/{fundamentals => security}/enterprise-auth.txt (100%) rename source/{fundamentals/connection => security}/socks.txt (100%) rename source/{fundamentals/connection => security}/tls.txt (100%) rename source/{ => security}/validate-signatures.txt (100%) diff --git a/config/redirects b/config/redirects index 5175739e5..5373422cc 100644 --- a/config/redirects +++ b/config/redirects @@ -5,9 +5,67 @@ define: versions v4.3 v4.4 v4.5 v4.6 v4.7 v4.8 v4.9 v4.10 v4.11 v5.0 v5.1 master raw: ${prefix}/ -> ${base}/current/ raw: ${prefix}/master -> ${base}/upcoming/ -[*-master]: ${prefix}/${version}/fundamentals/versioned-api/ -> ${base}/${version}/fundamentals/stable-api/ +[*-v5.2]: ${prefix}/${version}/fundamentals/versioned-api/ -> ${base}/${version}/fundamentals/stable-api/ [*-v4.6]: ${prefix}/${version}/fundamentals/crud/read-operations/change-streams/ -> ${base}/${version}/fundamentals/crud/read-operations/retrieve/ [*-master]: ${prefix}/${version}/fundamentals/csfle/ -> ${base}/${version}/fundamentals/encrypt-fields/ [*-master]: ${prefix}/${version}/fundamentals/crud/write-operations/change-a-document/ -> ${base}/${version}/fundamentals/crud/write-operations/modify/ [*-v4.10]: ${prefix}/${version}/fundamentals/connection/socks/ -> ${base}/${version}/ [*-v4.8]: ${prefix}/${version}/connection-troubleshooting/ -> ${base}/${version}/ +[v5.0-master]: ${prefix}/${version}/fundamentals/crud/ -> ${base}/${version}/crud/ +[v5.0-master]: ${prefix}/${version}/fundamentals/crud/read-operations/ -> ${base}/${version}/crud/read-operations/ +[v5.0-master]: ${prefix}/${version}/fundamentals/crud/read-operations/retrieve/ -> ${base}/${version}/crud/read-operations/retrieve/ +[v5.0-master]: ${prefix}/${version}/fundamentals/crud/read-operations/cursor/ -> ${base}/${version}/crud/read-operations/cursor/ +[v5.0-master]: ${prefix}/${version}/fundamentals/crud/read-operations/change-streams/ -> ${base}/${version}/logging-monitoring/change-streams/ +[v5.0-master]: ${prefix}/${version}/fundamentals/crud/read-operations/sort/ -> ${base}/${version}/crud/read-operations/sort/ +[v5.0-master]: ${prefix}/${version}/fundamentals/crud/read-operations/skip/ -> ${base}/${version}/crud/read-operations/skip/ +[v5.0-master]: ${prefix}/${version}/fundamentals/crud/read-operations/limit/ -> ${base}/${version}/crud/read-operations/limit/ +[v5.0-master]: ${prefix}/${version}/fundamentals/crud/read-operations/project/ -> ${base}/${version}/crud/read-operations/project/ +[v5.0-master]: ${prefix}/${version}/fundamentals/crud/read-operations/geo/ -> ${base}/${version}/crud/read-operations/geo/ +[v5.0-master]: ${prefix}/${version}/fundamentals/crud/read-operations/text/ -> ${base}/${version}/crud/read-operations/text/ +[v5.0-master]: ${prefix}/${version}/fundamentals/crud/write-operations/ -> ${base}/${version}/crud/write-operations/ +[v5.0-master]: ${prefix}/${version}/fundamentals/crud/write-operations/insert/ -> ${base}/${version}/crud/write-operations/insert/ +[v5.0-master]: ${prefix}/${version}/fundamentals/crud/write-operations/delete/ -> ${base}/${version}/crud/write-operations/delete/ +[v5.0-master]: ${prefix}/${version}/fundamentals/crud/write-operations/modify/ -> ${base}/${version}/crud/write-operations/modify/ +[v5.0-master]: ${prefix}/${version}/fundamentals/crud/write-operations/embedded-arrays/ -> ${base}/${version}/crud/write-operations/embedded-arrays/ +[v5.0-master]: ${prefix}/${version}/fundamentals/crud/write-operations/upsert/ -> ${base}/${version}/crud/write-operations/upsert/ +[v5.0-master]: ${prefix}/${version}/fundamentals/crud/write-operations/bulk/ -> ${base}/${version}/crud/write-operations/bulk/ +[v5.0-master]: ${prefix}/${version}/fundamentals/crud/query-document/ -> ${base}/${version}/crud/query-document/ +[v5.0-master]: ${prefix}/${version}/fundamentals/crud/compound-operations/ -> ${base}/${version}/crud/compound-operations/ +[v5.0-master]: ${prefix}/${version}/fundamentals/data-formats/ -> ${base}/${version}/data-formats/ +[v5.0-master]: ${prefix}/${version}/fundamentals/data-formats/document-data-format-bson/ -> ${base}/${version}/data-formats/document-data-format-bson/ +[v5.0-master]: ${prefix}/${version}/fundamentals/data-formats/document-data-format-extended-json/ -> ${base}/${version}/data-formats/document-data-format-extended-json/ +[v5.0-master]: ${prefix}/${version}/fundamentals/data-formats/documents/ -> ${base}/${version}/data-formats/documents/ +[v5.0-master]: ${prefix}/${version}/fundamentals/data-formats/document-data-format-pojo/ -> ${base}/${version}/data-formats/document-data-format-pojo/ +[v5.0-master]: ${prefix}/${version}/fundamentals/data-formats/document-data-format-record/ -> ${base}/${version}/data-formats/document-data-format-record/ +[v5.0-master]: ${prefix}/${version}/fundamentals/data-formats/pojo-customization/ -> ${base}/${version}/data-formats/pojo-customization/ +[v5.0-master]: ${prefix}/${version}/fundamentals/data-formats/codecs/ -> ${base}/${version}/data-formats/codecs/ +[v5.0-master]: ${prefix}/${version}/fundamentals/connection/ -> ${base}/${version}/connection/ +[v5.0-master]: ${prefix}/${version}/fundamentals/connection/connect/ -> ${base}/${version}/connection/connect/ +[v5.0-master]: ${prefix}/${version}/fundamentals/connection/connection-options/ -> ${base}/${version}/connection/connection-options/ +[v5.0-master]: ${prefix}/${version}/fundamentals/connection/mongoclientsettings/ -> ${base}/${version}/connection/mongoclientsettings/ +[v5.0-master]: ${prefix}/${version}/fundamentals/connection/network-compression/ -> ${base}/${version}/connection/network-compression/ +[v5.0-master]: ${prefix}/${version}/fundamentals/connection/socks/ -> ${base}/${version}/connection/socks/ +[v5.0-master]: ${prefix}/${version}/fundamentals/connection/tls/ -> ${base}/${version}/security/tls/ +[v5.0-master]: ${prefix}/${version}/fundamentals/connection/jndi/ -> ${base}/${version}/connection/jndi/ +[v5.0-master]: ${prefix}/${version}/fundamentals/builders/ -> ${base}/${version}/crud/builders/ +[v5.0-master]: ${prefix}/${version}/fundamentals/builders/aggregates/ -> ${base}/${version}/crud/builders/aggregates/ +[v5.0-master]: ${prefix}/${version}/fundamentals/builders/filters/ -> ${base}/${version}/crud/builders/filters/ +[v5.0-master]: ${prefix}/${version}/fundamentals/builders/indexes/ -> ${base}/${version}/crud/builders/indexes/ +[v5.0-master]: ${prefix}/${version}/fundamentals/builders/projections/ -> ${base}/${version}/crud/builders/projections/ +[v5.0-master]: ${prefix}/${version}/fundamentals/builders/sort/ -> ${base}/${version}/crud/builders/sort/ +[v5.0-master]: ${prefix}/${version}/fundamentals/builders/updates/ -> ${base}/${version}/crud/builders/updates/ +[v5.0-master]: ${prefix}/${version}/fundamentals/builders/vector-search -> ${base}/${version}/atlas-vector-search/ +[v5.0-master]: ${prefix}/${version}/fundamentals/aggregation/ -> ${base}/${version}/crud/aggregation/ +[v5.0-master]: ${prefix}/${version}/fundamentals/aggregation-expression-operations/ -> ${base}/${version}/crud/aggregation-expression-operations/ +[v5.0-master]: ${prefix}/${version}/fundamentals/collations/ -> ${base}/${version}/crud/collations/ +[v5.0-master]: ${prefix}/${version}/fundamentals/stable-api/ -> ${base}/${version}/connection/stable-api/ +[v5.0-master]: ${prefix}/${version}/connection-troubleshooting/ -> ${base}/${version}/connection/connection-troubleshooting/ +[v5.0-master]: ${prefix}/${version}/fundamentals/gridfs/ -> ${base}/${version}/crud/gridfs/ +[v5.0-master]: ${prefix}/${version}/fundamentals/transactions/ -> ${base}/${version}/crud/transactions/ +[v5.0-master]: ${prefix}/${version}/fundamentals/time-series/ -> ${base}/${version}/data-formats/time-series/ +[v5.0-master]: ${prefix}/${version}/quick-start/ -> ${base}/${version}/getting-started/ +[v5.0-master]: ${prefix}/${version}/fundamentals/databases-collections/ -> ${base}/${version}/getting-started/databases-collections/ +[v5.0-master]: ${prefix}/${version}/integrations/ -> ${base}/${version}/getting-started/integrations/ +[v5.0-master]: ${prefix}/${version}/quick-reference/ -> ${base}/${version}/getting-started/quick-reference/ +[v5.0-master]: ${prefix}/${version}/fundamentals/enterprise-auth/ -> ${base}/${version}/security/enterprise-auth/ +[v5.0-master]: ${prefix}/${version}/connection/socks/ -> ${base}/${version}/security/socks/ diff --git a/snooty.toml b/snooty.toml index bf4034de8..4c6c9829b 100644 --- a/snooty.toml +++ b/snooty.toml @@ -7,11 +7,13 @@ intersphinx = [ ] toc_landing_pages = [ - "/fundamentals/connection", - "/fundamentals/crud", - "/fundamentals/builders", - "/fundamentals/aggregation", - "/usage-examples", + "/getting-started", + "/connection", + "/crud", + "/aggregation", + "/builders", + "/data-formats", + "/api-documentation" ] sharedinclude_root = "https://raw.githubusercontent.com/10gen/docs-shared/main/" diff --git a/source/fundamentals/aggregation.txt b/source/aggregation.txt similarity index 98% rename from source/fundamentals/aggregation.txt rename to source/aggregation.txt index 0b6f5d247..a6a032035 100644 --- a/source/fundamentals/aggregation.txt +++ b/source/aggregation.txt @@ -17,6 +17,12 @@ Aggregation :depth: 2 :class: singlecol +.. toctree:: + :titlesonly: + :maxdepth: 1 + + Aggregation Expressions + Overview -------- diff --git a/source/fundamentals/aggregation-expression-operations.txt b/source/aggregation/aggregation-expression-operations.txt similarity index 100% rename from source/fundamentals/aggregation-expression-operations.txt rename to source/aggregation/aggregation-expression-operations.txt diff --git a/source/atlas-search.txt b/source/atlas-search.txt new file mode 100644 index 000000000..a21049881 --- /dev/null +++ b/source/atlas-search.txt @@ -0,0 +1,21 @@ +.. _java-atlas-search: + +============ +Atlas Search +============ + +.. facet:: + :name: genre + :values: reference + +.. meta:: + :keywords: full text, text analyzer, meta, pipeline, scoring, Lucene + :description: Learn about how to use Atlas Search in the {+driver-long+}. + +.. contents:: On this page + :local: + :backlinks: none + :depth: 2 + :class: singlecol + +See :atlas:`Atlas Search ` in the MongoDB Atlas documentation. \ No newline at end of file diff --git a/source/atlas-vector-search.txt b/source/atlas-vector-search.txt new file mode 100644 index 000000000..e60a1d487 --- /dev/null +++ b/source/atlas-vector-search.txt @@ -0,0 +1,107 @@ +.. _java-atlas-vector-search: + +=================== +Atlas Vector Search +=================== + +.. facet:: + :name: genre + :values: reference + +.. meta:: + :keywords: full text, text analyzer, meta, pipeline, scoring, Lucene, AI, artificial intelligence, code example, semantic, nearest + :description: Learn about how to use Atlas Vector Search in the {+driver-long+}. + +.. contents:: On this page + :local: + :backlinks: none + :depth: 2 + :class: singlecol + +Overview +-------- + +In this guide, you can learn how to use the :atlas:`Atlas Vector Search +` feature +in the {+driver-short+}. The ``Aggregates`` builders class provides the +the ``vectorSearch()`` helper method that you can use to +create a :atlas:`$vectorSearch ` +pipeline stage. This pipeline stage allows you to perform a **semantic +search** on your documents. A semantic search is a type of search which +locates information that is similar in meaning, but not necessarily +identical, to your provided search term or phrase. + +.. important:: Feature Compatibility + + To learn what versions of MongoDB Atlas support this feature, see + :atlas:`Limitations ` + in the MongoDB Atlas documentation. + +Perform a Vector Search +----------------------- + +To use this feature, you must create a vector search index and index your +vector embeddings. To learn about how to programmatically create a +vector search index, see the :ref:`java-search-indexes` section in the +Indexes guide. To learn more about vector embeddings, see +:atlas:`How to Index Vector Embeddings for Vector Search +` in the Atlas documentation. + +After you create a vector search index on your vector embeddings, you +can reference this index in your pipeline stage, as shown in the +following section. + +Vector Search Example +~~~~~~~~~~~~~~~~~~~~~ + +The following example shows how to build an aggregation pipeline that uses the +``vectorSearch()`` and ``project()`` methods to compute a vector search score: + +.. literalinclude:: /includes/fundamentals/code-snippets/builders/AggBuilders.java + :start-after: // begin vectorSearch + :end-before: // end vectorSearch + :language: java + :dedent: + +.. tip:: Query Vector Type + + The preceding example creates an instance of ``BinaryVector`` to + serve as the query vector, but you can also create a ``List`` of + ``Double`` instances. However, we recommend that you use the + ``BinaryVector`` type to improve storage efficiency. + +The following example shows how you can run the aggregation and print +the vector search meta-score from the result of the preceding +aggregation pipeline: + +.. literalinclude:: /includes/fundamentals/code-snippets/builders/AggBuilders.java + :start-after: // begin vectorSearch-output + :end-before: // end vectorSearch-output + :language: java + :dedent: + +.. tip:: Java Driver Vector Search Examples + + Visit the :atlas:`Atlas documentation ` + to find more tutorials on using the {+driver-short+} to perform Atlas + Vector Searches. + +API Documentation +----------------- + +To learn more about the methods and types mentioned in this +guide, see the following API documentation: + +- `Aggregates.vectorSearch() + <{+api+}/apidocs/mongodb-driver-core/com/mongodb/client/model/Aggregates.html#vectorSearch(com.mongodb.client.model.search.FieldSearchPath,java.lang.Iterable,java.lang.String,long,com.mongodb.client.model.search.VectorSearchOptions)>`__ + +- `FieldSearchPath + <{+api+}/apidocs/mongodb-driver-core/com/mongodb/client/model/search/FieldSearchPath.html>`__ + +- `VectorSearchOptions + <{+api+}/apidocs/mongodb-driver-core/com/mongodb/client/model/search/VectorSearchOptions.html>`__ + +- `Projections.metaVectorSearchScore() + <{+api+}/apidocs/mongodb-driver-core/com/mongodb/client/model/Projections.html#metaVectorSearchScore(java.lang.String)>`__ + +- `BinaryVector <{+api+}/apidocs/bson/org/bson/BinaryVector.html>`__ \ No newline at end of file diff --git a/source/fundamentals/builders.txt b/source/builders.txt similarity index 91% rename from source/fundamentals/builders.txt rename to source/builders.txt index ee1e92425..1bcd498e3 100644 --- a/source/fundamentals/builders.txt +++ b/source/builders.txt @@ -8,12 +8,12 @@ Builders .. toctree:: - Aggregation - Filters - Indexes - Projection - Sort - Update + Aggregation + Filters + Indexes + Projection + Sort + Update .. contents:: On this page :local: diff --git a/source/fundamentals/builders/aggregates.txt b/source/builders/aggregates.txt similarity index 99% rename from source/fundamentals/builders/aggregates.txt rename to source/builders/aggregates.txt index 4b9b2b58f..f0c8dd495 100644 --- a/source/fundamentals/builders/aggregates.txt +++ b/source/builders/aggregates.txt @@ -15,6 +15,10 @@ Aggregates Builders :depth: 2 :class: singlecol +.. toctree:: + + Atlas Vector Search + .. _aggregates-builders: Overview @@ -86,7 +90,7 @@ Project Use the ``project()`` method to create a :manual:`$project ` pipeline stage that project specified document fields. Field projection -in aggregation follows the same rules as :doc:`field projection in queries `. +in aggregation follows the same rules as :doc:`field projection in queries `. .. tip:: diff --git a/source/fundamentals/builders/filters.txt b/source/builders/filters.txt similarity index 99% rename from source/fundamentals/builders/filters.txt rename to source/builders/filters.txt index 71ed5a209..2681e9150 100644 --- a/source/fundamentals/builders/filters.txt +++ b/source/builders/filters.txt @@ -20,7 +20,7 @@ In this guide, you can learn how to use **builders** to specify Builders are classes provided by the MongoDB Java driver that help you construct :ref:`BSON ` objects. To learn more, see our :doc:`guide -on builders `. +on builders `. Filters are the operations MongoDB uses to limit your results to what you want to see. diff --git a/source/fundamentals/builders/indexes.txt b/source/builders/indexes.txt similarity index 98% rename from source/fundamentals/builders/indexes.txt rename to source/builders/indexes.txt index cf650829b..888b15f9a 100644 --- a/source/fundamentals/builders/indexes.txt +++ b/source/builders/indexes.txt @@ -16,7 +16,7 @@ Overview -------- In this guide, you can learn how to specify **indexes** using -:doc:`builders ` in the MongoDB Java driver. +:doc:`builders ` in the MongoDB Java driver. The ``Indexes`` builder provides helper methods for constructing the following types of indexes: diff --git a/source/fundamentals/builders/projections.txt b/source/builders/projections.txt similarity index 99% rename from source/fundamentals/builders/projections.txt rename to source/builders/projections.txt index e4e321ca8..f11815add 100644 --- a/source/fundamentals/builders/projections.txt +++ b/source/builders/projections.txt @@ -16,7 +16,7 @@ Overview -------- In this guide, you can learn how to specify **projections** using -:doc:`builders ` in the MongoDB Java driver. +:doc:`builders ` in the MongoDB Java driver. MongoDB supports **field projection**, specifying which fields to include and exclude when returning results from a query. Projection in MongoDB follows some basic rules: diff --git a/source/fundamentals/builders/sort.txt b/source/builders/sort.txt similarity index 97% rename from source/fundamentals/builders/sort.txt rename to source/builders/sort.txt index 59b1e9e97..f73f01b2e 100644 --- a/source/fundamentals/builders/sort.txt +++ b/source/builders/sort.txt @@ -32,14 +32,14 @@ examples of sort criteria are: Builders are classes provided by the MongoDB Java driver that help you construct :ref:`BSON ` objects. To learn more, see our :doc:`guide -on builders `. +on builders `. You should read this guide if you would like to use builders to specify sort criteria for your queries. If you want to learn the fundamentals of sorting in the MongoDB Java driver, consider reading our -:doc:`guide on sorting `. +:doc:`guide on sorting `. .. _sorts-builders-sort-sample: @@ -63,7 +63,7 @@ criteria operators supported by MongoDB. These methods return a ``Bson`` object that you can pass to the ``sort()`` method of a ``FindIterable`` instance or to ``Aggregates.sort()``. If you want to learn more about the ``Aggregates`` class, see our -:doc:`guide on the Aggregates builder `. +:doc:`guide on the Aggregates builder `. For more information about the classes and interfaces in this section, see the following API Documentation: diff --git a/source/fundamentals/builders/updates.txt b/source/builders/updates.txt similarity index 100% rename from source/fundamentals/builders/updates.txt rename to source/builders/updates.txt diff --git a/source/usage-examples/command.txt b/source/command.txt similarity index 100% rename from source/usage-examples/command.txt rename to source/command.txt diff --git a/source/fundamentals/connection.txt b/source/connection.txt similarity index 73% rename from source/fundamentals/connection.txt rename to source/connection.txt index 63969b0f1..d34dc63f2 100644 --- a/source/fundamentals/connection.txt +++ b/source/connection.txt @@ -6,13 +6,13 @@ Connection Guide .. toctree:: - Connect to MongoDB - Connection Options - MongoClient Settings - Network Compression - TLS/SSL - SOCKS5 Proxy - JNDI Datasource + Connect to MongoDB + Connection Options + MongoClient Settings + Stable API + Network Compression + JNDI Datasource + Connection Troubleshooting AWS Lambda .. contents:: On this page diff --git a/source/fundamentals/connection/connect.txt b/source/connection/connect.txt similarity index 97% rename from source/fundamentals/connection/connect.txt rename to source/connection/connect.txt index 713a350bb..6e122095a 100644 --- a/source/fundamentals/connection/connect.txt +++ b/source/connection/connect.txt @@ -26,9 +26,7 @@ Use the ``MongoClients.create()`` method to construct a ``MongoClient``. As each ``MongoClient`` represents a thread-safe pool of connections to the database, most applications only require a single instance of a - ``MongoClient``, even across multiple threads. To learn more about - how connection pools work in the driver, see the :ref:`FAQ page `. - + ``MongoClient``, even across multiple threads. All resource usage limits, such as max connections, apply to individual ``MongoClient`` instances. diff --git a/source/fundamentals/connection/connection-options.txt b/source/connection/connection-options.txt similarity index 99% rename from source/fundamentals/connection/connection-options.txt rename to source/connection/connection-options.txt index 9e53569d2..517b9b842 100644 --- a/source/fundamentals/connection/connection-options.txt +++ b/source/connection/connection-options.txt @@ -194,7 +194,7 @@ parameters of the connection URI to specify the behavior of the client. * - **authMechanism** - string - Specifies the :doc:`authentication mechanism - ` that the driver uses if a credential + ` that the driver uses if a credential was supplied. | **Default**: By default, the client picks the most secure diff --git a/source/connection-troubleshooting.txt b/source/connection/connection-troubleshooting.txt similarity index 97% rename from source/connection-troubleshooting.txt rename to source/connection/connection-troubleshooting.txt index b05ba4ce5..a4a79c6bd 100644 --- a/source/connection-troubleshooting.txt +++ b/source/connection/connection-troubleshooting.txt @@ -31,8 +31,6 @@ Connection Troubleshooting finding more resources - The `MongoDB Community Forums <{+communityForums+}>`__ for questions, discussions, or general technical support - - The :ref:`Frequently Asked Questions (FAQ) ` page for - answers to common questions about the {+driver-short+} .. replacement:: server-selection-timeout-error @@ -150,11 +148,6 @@ Connection Troubleshooting ``maxIdleTimeMS`` - .. replacement:: connection-pools-learn-more - - To learn more about how connection pooling works in the driver, see - :ref:`java-faq-connection-pool` in the FAQ. - .. replacement:: scram-failure-error .. code-block:: diff --git a/source/fundamentals/connection/jndi.txt b/source/connection/jndi.txt similarity index 100% rename from source/fundamentals/connection/jndi.txt rename to source/connection/jndi.txt diff --git a/source/fundamentals/connection/mongoclientsettings.txt b/source/connection/mongoclientsettings.txt similarity index 100% rename from source/fundamentals/connection/mongoclientsettings.txt rename to source/connection/mongoclientsettings.txt diff --git a/source/fundamentals/connection/network-compression.txt b/source/connection/network-compression.txt similarity index 100% rename from source/fundamentals/connection/network-compression.txt rename to source/connection/network-compression.txt diff --git a/source/fundamentals/stable-api.txt b/source/connection/stable-api.txt similarity index 100% rename from source/fundamentals/stable-api.txt rename to source/connection/stable-api.txt diff --git a/source/crud.txt b/source/crud.txt new file mode 100644 index 000000000..f64c94fe0 --- /dev/null +++ b/source/crud.txt @@ -0,0 +1,28 @@ +.. _java-crud-operations: + +=============== +CRUD Operations +=============== + +.. toctree:: + :caption: CRUD Operations + + Read + Write + Query + Compound Operations + Transactions + Collations + Large File Storage with GridFS + +CRUD (Create, Read, Update, Delete) operations enable you to work with +data stored in MongoDB. + +- :ref:`Read Operations ` find and return + documents stored in your database. +- :ref:`Write Operations ` insert, modify, + or delete documents in your database. + +Some operations combine aspects of read and write operations. See our +guide on :ref:`compound operations ` +to learn more about these hybrid methods. diff --git a/source/fundamentals/collations.txt b/source/crud/collations.txt similarity index 100% rename from source/fundamentals/collations.txt rename to source/crud/collations.txt diff --git a/source/fundamentals/crud/compound-operations.txt b/source/crud/compound-operations.txt similarity index 96% rename from source/fundamentals/crud/compound-operations.txt rename to source/crud/compound-operations.txt index 9cc4277fc..d8c7a0b86 100644 --- a/source/fundamentals/crud/compound-operations.txt +++ b/source/crud/compound-operations.txt @@ -1,3 +1,5 @@ +.. _java-compound-operations: + =================== Compound Operations =================== @@ -101,10 +103,10 @@ The output of the preceding code resembles the following: {"food": "pizza", "color": "green"} For more information about the ``Projections`` class, see our -:doc:`guide on the Projections builder `. +:doc:`guide on the Projections builder `. For more information about the upsert operation, see our -:doc:`guide on upserts `. +:doc:`guide on upserts `. For more information about the methods and classes mentioned in this section, see the following API Documentation: @@ -187,7 +189,7 @@ The output of the preceding code resembles the following: {"_id": 2, "food": "pear", "color": "yellow"} For more information about the ``Sorts`` class, see our -:doc:`guide on the Sorts builder `. +:doc:`guide on the Sorts builder `. For more information about the methods and classes mentioned in this section, see the following API Documentation: @@ -318,10 +320,10 @@ instance: for the duration of your compound operation. For information on the ``Updates`` class, see our -:doc:`guide on the Updates builder `. +:doc:`guide on the Updates builder `. For more information of the ``Filters`` class, see our -:doc:`guide on the Filters builder `. +:doc:`guide on the Filters builder `. For more information about the ``findOneAndUpdate()`` method, see the API Documentation for the `MongoCollection class <{+api+}/apidocs/mongodb-driver-sync/com/mongodb/client/MongoCollection.html#findOneAndUpdate(org.bson.conversions.Bson,java.util.List,com.mongodb.client.model.FindOneAndUpdateOptions)>`__. diff --git a/source/fundamentals/gridfs.txt b/source/crud/gridfs.txt similarity index 97% rename from source/fundamentals/gridfs.txt rename to source/crud/gridfs.txt index e3ba3d562..bd47e7dc2 100644 --- a/source/fundamentals/gridfs.txt +++ b/source/crud/gridfs.txt @@ -1,8 +1,15 @@ -====== -GridFS -====== +============================== +Large File Storage with GridFS +============================== .. default-domain:: mongodb +.. facet:: + :name: genre + :values: reference + +.. meta:: + :keywords: retrieve, size limit + :description: Store large files with GridFS in the {+driver-long+}. .. contents:: On this page :local: @@ -257,8 +264,8 @@ see the following resources: - `GridFSFindIterable <{+api+}/apidocs/mongodb-driver-sync/com/mongodb/client/gridfs/GridFSFindIterable.html>`__ API Documentation - `GridFSBucket.find() <{+api+}/apidocs/mongodb-driver-sync/com/mongodb/client/gridfs/GridFSBucket.html#find(org.bson.conversions.Bson)>`__ API Documentation -- :doc:`Sort Results ` -- :doc:`Limit the Number of Returned Results ` +- :doc:`Sort Results ` +- :doc:`Limit the Number of Returned Results ` .. _gridfs-download-files: diff --git a/source/fundamentals/crud/query-document.txt b/source/crud/query-document.txt similarity index 100% rename from source/fundamentals/crud/query-document.txt rename to source/crud/query-document.txt diff --git a/source/crud/read-operations.txt b/source/crud/read-operations.txt new file mode 100644 index 000000000..1c9183ea0 --- /dev/null +++ b/source/crud/read-operations.txt @@ -0,0 +1,29 @@ +.. _java-read-operations: + +=============== +Read Operations +=============== + +.. meta:: + :description: Learn about the commands for running read operations on MongoDB by using the {+driver-long+}. + +.. toctree:: + :caption: Read Operations + + Retrieve Data + Data from a Cursor + Sort Results + Skip Returned Results + Limit Returned Results + Specify Fields to Return + Geospatial Data + Search Text + +- :doc:`/crud/read-operations/retrieve` +- :doc:`/crud/read-operations/cursor` +- :doc:`/crud/read-operations/sort` +- :doc:`/crud/read-operations/skip` +- :doc:`/crud/read-operations/limit` +- :doc:`/crud/read-operations/project` +- :doc:`/crud/read-operations/geo` +- :doc:`/crud/read-operations/text` diff --git a/source/fundamentals/crud/read-operations/cursor.txt b/source/crud/read-operations/cursor.txt similarity index 100% rename from source/fundamentals/crud/read-operations/cursor.txt rename to source/crud/read-operations/cursor.txt diff --git a/source/fundamentals/crud/read-operations/geo.txt b/source/crud/read-operations/geo.txt similarity index 97% rename from source/fundamentals/crud/read-operations/geo.txt rename to source/crud/read-operations/geo.txt index a0f5f400e..58f7e8e57 100644 --- a/source/fundamentals/crud/read-operations/geo.txt +++ b/source/crud/read-operations/geo.txt @@ -98,7 +98,7 @@ GeoJSON data to a ``2dsphere`` index. The following snippet creates a collection.createIndex(Indexes.geo2dsphere("location.geo")); For more information about the ``Indexes`` builder, see our -:doc:`guide on the Indexes builder `. +:doc:`guide on the Indexes builder `. .. guide resource @@ -131,7 +131,7 @@ legacy coordinate pairs to a ``2d`` index. The following snippet creates a collection.createIndex(Indexes.geo2d("coordinates")); For more information about the ``Indexes`` builder, see our -:doc:`guide on the Indexes builder `. +:doc:`guide on the Indexes builder `. For more information about legacy coordinate pairs, see the :manual:`{+mdb-server+} manual page on legacy coordinate pairs `. @@ -173,7 +173,7 @@ For more information about geospatial query operators, see the .. external resource For more information about ``Filters``, see our -:doc:`guide on the Filters builder `. +:doc:`guide on the Filters builder `. Query Parameters ~~~~~~~~~~~~~~~~ @@ -258,7 +258,7 @@ For more information about the ``$near`` operator, see :manual:`the reference documentation for $near `. For more information about ``Filters``, -:doc:`see our guide on the Filters builder `. +:doc:`see our guide on the Filters builder `. Query Within a Range ~~~~~~~~~~~~~~~~~~~~ diff --git a/source/fundamentals/crud/read-operations/limit.txt b/source/crud/read-operations/limit.txt similarity index 98% rename from source/fundamentals/crud/read-operations/limit.txt rename to source/crud/read-operations/limit.txt index cac0b5f8f..49d384106 100644 --- a/source/fundamentals/crud/read-operations/limit.txt +++ b/source/crud/read-operations/limit.txt @@ -25,7 +25,7 @@ to reach the specified limit, it can return a smaller number. If you use ``limit()`` with the ``skip()`` instance method, the skip applies first and the limit only applies to the documents left over after the skip. For more information about the ``skip()`` method, see our -:doc:`guide on Skipping Returned Documents `. +:doc:`guide on Skipping Returned Documents `. The following examples demonstrate, respectively, how to insert data into a collection, how to use ``limit()`` to restrict the number of returned documents, diff --git a/source/fundamentals/crud/read-operations/project.txt b/source/crud/read-operations/project.txt similarity index 100% rename from source/fundamentals/crud/read-operations/project.txt rename to source/crud/read-operations/project.txt diff --git a/source/fundamentals/crud/read-operations/retrieve.txt b/source/crud/read-operations/retrieve.txt similarity index 98% rename from source/fundamentals/crud/read-operations/retrieve.txt rename to source/crud/read-operations/retrieve.txt index 806e60b91..02dba978d 100644 --- a/source/fundamentals/crud/read-operations/retrieve.txt +++ b/source/crud/read-operations/retrieve.txt @@ -54,7 +54,7 @@ To perform a find operation, call the ``find()`` method on an instance of a ``MongoCollection``. This method searches a collection for documents that match the query filter you provide. For more information about how to specify a query, see our :doc:`Specify a Query -` guide. +` guide. Example ~~~~~~~ @@ -71,7 +71,7 @@ To address this scenario, the owner finds orders to match the criteria: :end-before: end findExample For more information about how to build filters, see our :doc:`Filters Builders -` guide. +` guide. The following shows the output of the preceding query: diff --git a/source/fundamentals/crud/read-operations/skip.txt b/source/crud/read-operations/skip.txt similarity index 100% rename from source/fundamentals/crud/read-operations/skip.txt rename to source/crud/read-operations/skip.txt diff --git a/source/fundamentals/crud/read-operations/sort.txt b/source/crud/read-operations/sort.txt similarity index 98% rename from source/fundamentals/crud/read-operations/sort.txt rename to source/crud/read-operations/sort.txt index aa31654bb..b0cccdbad 100644 --- a/source/fundamentals/crud/read-operations/sort.txt +++ b/source/crud/read-operations/sort.txt @@ -97,7 +97,7 @@ builder class. While it is possible to specify sort criteria using any class that implements the ``Bson`` interface, we recommend that you specify sort criteria through the ``Sorts`` builder. For more information about the ``Sorts`` builder class, see our -:doc:`guide on the Sorts builder `. +:doc:`guide on the Sorts builder `. For more information about the classes and interfaces in this section, see the following API Documentation: @@ -328,9 +328,9 @@ sort by the text score. In the following code example, we show how you can use the ``Sorts.metaTextScore()`` method to sort the results of a text search on the :ref:`sample collection `. -The code example uses the :doc:`Filters `, -:doc:`Indexes `, and -:doc:`Projections ` builders. +The code example uses the :doc:`Filters `, +:doc:`Indexes `, and +:doc:`Projections ` builders. The code example performs the following actions: #. Creates a text index for your diff --git a/source/fundamentals/crud/read-operations/text.txt b/source/crud/read-operations/text.txt similarity index 99% rename from source/fundamentals/crud/read-operations/text.txt rename to source/crud/read-operations/text.txt index 8dc7b200b..3618366f7 100644 --- a/source/fundamentals/crud/read-operations/text.txt +++ b/source/crud/read-operations/text.txt @@ -83,7 +83,7 @@ Text Search Use the ``Filters.text()`` method to specify a text search. The ``Filters.text()`` method uses the :doc:`Filters builder -` to define a query filter specifying +` to define a query filter specifying what to search for during the text search. The query filter is represented by a :ref:`BSON ` instance. Pass the query filter to the ``find()`` method to run a text search. diff --git a/source/fundamentals/transactions.txt b/source/crud/transactions.txt similarity index 100% rename from source/fundamentals/transactions.txt rename to source/crud/transactions.txt diff --git a/source/crud/write-operations.txt b/source/crud/write-operations.txt new file mode 100644 index 000000000..aa0b2d86a --- /dev/null +++ b/source/crud/write-operations.txt @@ -0,0 +1,25 @@ +.. _java-write-operations: + +================ +Write Operations +================ + +.. meta:: + :description: Learn about the commands for running MongoDB write operations by using the {+driver-long+}. + +.. toctree:: + :caption: Write Operations + + Insert + Delete + Modify + Update Array Elements + Upsert + Bulk Operations + +- :doc:`/crud/write-operations/insert` +- :doc:`/crud/write-operations/delete` +- :doc:`/crud/write-operations/modify` +- :doc:`/crud/write-operations/embedded-arrays` +- :doc:`/crud/write-operations/upsert` +- :doc:`/crud/write-operations/bulk` diff --git a/source/fundamentals/crud/write-operations/bulk.txt b/source/crud/write-operations/bulk.txt similarity index 100% rename from source/fundamentals/crud/write-operations/bulk.txt rename to source/crud/write-operations/bulk.txt diff --git a/source/fundamentals/crud/write-operations/delete.txt b/source/crud/write-operations/delete.txt similarity index 100% rename from source/fundamentals/crud/write-operations/delete.txt rename to source/crud/write-operations/delete.txt diff --git a/source/fundamentals/crud/write-operations/embedded-arrays.txt b/source/crud/write-operations/embedded-arrays.txt similarity index 98% rename from source/fundamentals/crud/write-operations/embedded-arrays.txt rename to source/crud/write-operations/embedded-arrays.txt index bde25f636..0a9c2d921 100644 --- a/source/fundamentals/crud/write-operations/embedded-arrays.txt +++ b/source/crud/write-operations/embedded-arrays.txt @@ -39,7 +39,7 @@ The examples on this page use the ``findOneAndUpdate()`` method of the example uses an instance of the ``FindOneAndUpdateOptions`` class to have MongoDB retrieve the document after the update occurs. For more information on the ``findOneAndUpdate()`` method, see our -:doc:`Compound Operations guide `. +:doc:`Compound Operations guide `. Specifying an Update -------------------- diff --git a/source/fundamentals/crud/write-operations/insert.txt b/source/crud/write-operations/insert.txt similarity index 98% rename from source/fundamentals/crud/write-operations/insert.txt rename to source/crud/write-operations/insert.txt index 5bedc1340..39a4c8051 100644 --- a/source/fundamentals/crud/write-operations/insert.txt +++ b/source/crud/write-operations/insert.txt @@ -30,7 +30,7 @@ methods. The following sections focus on ``insertOne()`` and ``insertMany()``. For information on how to use the ``bulkWrite()`` method, see our -:doc:`guide on Bulk Operations `. +:doc:`guide on Bulk Operations `. A Note About ``_id`` -------------------- diff --git a/source/fundamentals/crud/write-operations/modify.txt b/source/crud/write-operations/modify.txt similarity index 97% rename from source/fundamentals/crud/write-operations/modify.txt rename to source/crud/write-operations/modify.txt index 42c4f6081..991066be2 100644 --- a/source/fundamentals/crud/write-operations/modify.txt +++ b/source/crud/write-operations/modify.txt @@ -118,7 +118,7 @@ The following shows the updated documents in the ``paint_inventory`` collection: If zero documents match the query filter in the update operation, ``updateMany()`` makes no changes to documents in the collection. See -our :doc:`upsert guide ` to +our :doc:`upsert guide ` to learn how to insert a new document instead of updating one if no documents match. @@ -194,7 +194,7 @@ The following shows the updated document: If zero documents match the query filter in the replace operation, ``replaceOne()`` makes no changes to documents in the collection. See -our :doc:`upsert guide ` to +our :doc:`upsert guide ` to learn how to insert a new document instead of replacing one if no documents match. diff --git a/source/fundamentals/crud/write-operations/upsert.txt b/source/crud/write-operations/upsert.txt similarity index 100% rename from source/fundamentals/crud/write-operations/upsert.txt rename to source/crud/write-operations/upsert.txt diff --git a/source/data-formats.txt b/source/data-formats.txt new file mode 100644 index 000000000..f553fbc97 --- /dev/null +++ b/source/data-formats.txt @@ -0,0 +1,26 @@ +============ +Data Formats +============ + +.. meta:: + :description: Learn how to convert between MongoDB and Java data formats by using the {+driver-long+}. + +.. toctree:: + :caption: Data Formats + + BSON + Extended JSON + Documents + POJOs + POJO Customization + Records + Codecs + Time Series Collections + +- :doc:`/data-formats/document-data-format-bson` +- :doc:`/data-formats/document-data-format-extended-json` +- :doc:`/data-formats/documents` +- :doc:`/data-formats/document-data-format-pojo` +- :doc:`/data-formats/document-data-format-record` +- :doc:`/data-formats/pojo-customization` +- :doc:`/data-formats/codecs` diff --git a/source/fundamentals/data-formats/codecs.txt b/source/data-formats/codecs.txt similarity index 100% rename from source/fundamentals/data-formats/codecs.txt rename to source/data-formats/codecs.txt diff --git a/source/fundamentals/data-formats/document-data-format-bson.txt b/source/data-formats/document-data-format-bson.txt similarity index 100% rename from source/fundamentals/data-formats/document-data-format-bson.txt rename to source/data-formats/document-data-format-bson.txt diff --git a/source/fundamentals/data-formats/document-data-format-extended-json.txt b/source/data-formats/document-data-format-extended-json.txt similarity index 100% rename from source/fundamentals/data-formats/document-data-format-extended-json.txt rename to source/data-formats/document-data-format-extended-json.txt diff --git a/source/fundamentals/data-formats/document-data-format-pojo.txt b/source/data-formats/document-data-format-pojo.txt similarity index 100% rename from source/fundamentals/data-formats/document-data-format-pojo.txt rename to source/data-formats/document-data-format-pojo.txt diff --git a/source/fundamentals/data-formats/document-data-format-record.txt b/source/data-formats/document-data-format-record.txt similarity index 100% rename from source/fundamentals/data-formats/document-data-format-record.txt rename to source/data-formats/document-data-format-record.txt diff --git a/source/fundamentals/data-formats/documents.txt b/source/data-formats/documents.txt similarity index 100% rename from source/fundamentals/data-formats/documents.txt rename to source/data-formats/documents.txt diff --git a/source/fundamentals/data-formats/pojo-customization.txt b/source/data-formats/pojo-customization.txt similarity index 100% rename from source/fundamentals/data-formats/pojo-customization.txt rename to source/data-formats/pojo-customization.txt diff --git a/source/fundamentals/time-series.txt b/source/data-formats/time-series.txt similarity index 97% rename from source/fundamentals/time-series.txt rename to source/data-formats/time-series.txt index fb963c114..dc485ba37 100644 --- a/source/fundamentals/time-series.txt +++ b/source/data-formats/time-series.txt @@ -95,7 +95,7 @@ Query a Time Series Collection ------------------------------ To query in a time series collection, use the same conventions as you -would for :doc:`retrieving ` +would for :doc:`retrieving ` and :ref:`aggregating data `. .. note:: Window Functions diff --git a/source/fundamentals/databases-collections.txt b/source/databases-collections.txt similarity index 100% rename from source/fundamentals/databases-collections.txt rename to source/databases-collections.txt diff --git a/source/fundamentals.txt b/source/fundamentals.txt deleted file mode 100644 index 019c88bd7..000000000 --- a/source/fundamentals.txt +++ /dev/null @@ -1,31 +0,0 @@ -============ -Fundamentals -============ - -.. meta:: - :description: Learn how to use the (+driver-long+} to run commands on MongoDB. - -.. toctree:: - :titlesonly: - :maxdepth: 1 - - Connection Guide - Authentication - Enterprise Authentication - Stable API - Databases & Collections - Data Formats - CRUD Operations - Builders - Aggregation - Aggregation Expressions - Indexes - Transactions - Collations - Logging - Monitoring - GridFS - In-Use Encryption - Time Series Collections - -.. include:: /includes/fundamentals-sections.rst diff --git a/source/fundamentals/crud.txt b/source/fundamentals/crud.txt deleted file mode 100644 index 3417cd5e0..000000000 --- a/source/fundamentals/crud.txt +++ /dev/null @@ -1,27 +0,0 @@ -.. _java-crud-operations: - -=============== -CRUD Operations -=============== - -.. default-domain:: mongodb - -.. toctree:: - :caption: CRUD Operations - - Read - Write - Query - Compound Operations - -CRUD (Create, Read, Update, Delete) operations enable you to work with -data stored in MongoDB. - -- :doc:`Read Operations ` find and return - documents stored in your database. -- :doc:`Write Operations ` insert, modify, - or delete documents in your database. - -Some operations combine aspects of read and write operations. See our -guide on :doc:`compound operations ` -to learn more about these hybrid methods. diff --git a/source/fundamentals/crud/read-operations.txt b/source/fundamentals/crud/read-operations.txt deleted file mode 100644 index 0eb147951..000000000 --- a/source/fundamentals/crud/read-operations.txt +++ /dev/null @@ -1,29 +0,0 @@ -=============== -Read Operations -=============== - -.. meta:: - :description: Learn about the commands for running read operations on MongoDB by using the {+driver-long+}. - -.. toctree:: - :caption: Read Operations - - Retrieve Data - Data from a Cursor - Open Change Streams - Sort Results - Skip Returned Results - Limit Returned Results - Specify Fields to Return - Geospatial Data - Search Text - -- :doc:`/fundamentals/crud/read-operations/retrieve` -- :doc:`/fundamentals/crud/read-operations/cursor` -- :doc:`/fundamentals/crud/read-operations/change-streams` -- :doc:`/fundamentals/crud/read-operations/sort` -- :doc:`/fundamentals/crud/read-operations/skip` -- :doc:`/fundamentals/crud/read-operations/limit` -- :doc:`/fundamentals/crud/read-operations/project` -- :doc:`/fundamentals/crud/read-operations/geo` -- :doc:`/fundamentals/crud/read-operations/text` diff --git a/source/fundamentals/crud/write-operations.txt b/source/fundamentals/crud/write-operations.txt deleted file mode 100644 index fd4e57d6a..000000000 --- a/source/fundamentals/crud/write-operations.txt +++ /dev/null @@ -1,23 +0,0 @@ -================ -Write Operations -================ - -.. meta:: - :description: Learn about the commands for running MongoDB write operations by using the {+driver-long+}. - -.. toctree:: - :caption: Write Operations - - Insert - Delete - Modify - Update Array Elements - Upsert - Bulk Operations - -- :doc:`/fundamentals/crud/write-operations/insert` -- :doc:`/fundamentals/crud/write-operations/delete` -- :doc:`/fundamentals/crud/write-operations/modify` -- :doc:`/fundamentals/crud/write-operations/embedded-arrays` -- :doc:`/fundamentals/crud/write-operations/upsert` -- :doc:`/fundamentals/crud/write-operations/bulk` diff --git a/source/fundamentals/data-formats.txt b/source/fundamentals/data-formats.txt deleted file mode 100644 index a26dfd099..000000000 --- a/source/fundamentals/data-formats.txt +++ /dev/null @@ -1,25 +0,0 @@ -============ -Data Formats -============ - -.. meta:: - :description: Learn how to convert between MongoDB and Java data formats by using the {+driver-long+}. - -.. toctree:: - :caption: Data Formats - - BSON - Extended JSON - Documents - POJOs - Records - POJO Customization - Codecs - -- :doc:`/fundamentals/data-formats/document-data-format-bson` -- :doc:`/fundamentals/data-formats/document-data-format-extended-json` -- :doc:`/fundamentals/data-formats/documents` -- :doc:`/fundamentals/data-formats/document-data-format-pojo` -- :doc:`/fundamentals/data-formats/document-data-format-record` -- :doc:`/fundamentals/data-formats/pojo-customization` -- :doc:`/fundamentals/data-formats/codecs` diff --git a/source/quick-start.txt b/source/getting-started.txt similarity index 92% rename from source/quick-start.txt rename to source/getting-started.txt index 1aeb7ab4e..f76d668b1 100644 --- a/source/quick-start.txt +++ b/source/getting-started.txt @@ -1,8 +1,8 @@ .. _java-sync-quickstart: -======================= -Java Driver Quick Start -======================= +=============== +Getting Started +=============== .. facet:: :name: genre @@ -17,6 +17,12 @@ Java Driver Quick Start :depth: 2 :class: singlecol +.. toctree:: + :titlesonly: + :maxdepth: 1 + + Quick Reference + Introduction ------------ @@ -127,8 +133,8 @@ the password you created for your user that has **atlasAdmin** permissions: See the following links For more information about using POJOs to store and retrieve data: -- :doc:`Guide on using POJOs to store and retrieve data` -- :doc:`Guide on custom serialization of POJOs ` +- :doc:`Guide on using POJOs to store and retrieve data` +- :doc:`Guide on custom serialization of POJOs ` Next steps ---------- diff --git a/source/quick-reference.txt b/source/getting-started/quick-reference.txt similarity index 100% rename from source/quick-reference.txt rename to source/getting-started/quick-reference.txt diff --git a/source/index.txt b/source/index.txt index 5399663d5..74896d726 100644 --- a/source/index.txt +++ b/source/index.txt @@ -18,21 +18,23 @@ MongoDB Java Driver :titlesonly: :maxdepth: 1 - Quick Start - Quick Reference - What's New - Usage Examples - Fundamentals + Getting Started + Connect + CRUD Operations + Databases and Collations + Aggregation + Builders + Data Formats + Indexes + Run a Command + Atlas Search + Atlas Vector Search + Logging and Monitoring + Security + Third-Party Integrations + Reference API Documentation - FAQ - Connection Troubleshooting Issues & Help - Driver Integrations - Compatibility - Upgrade - Validate Driver Signatures - Migrate from the Legacy API - View the Source Introduction ------------ @@ -115,13 +117,6 @@ and links to the API documentation. * - `Legacy Java Driver <{+api+}/apidocs/mongodb-driver-legacy/index.html>`__ - Legacy API -FAQ ---- - -For answers to commonly asked questions about the MongoDB -Java Driver, see the :doc:`Frequently Asked Questions (FAQ) ` -section. - Connection Troubleshooting -------------------------- diff --git a/source/fundamentals/indexes.txt b/source/indexes.txt similarity index 100% rename from source/fundamentals/indexes.txt rename to source/indexes.txt diff --git a/source/integrations.txt b/source/integrations.txt index d8929a1ca..fa329cc8a 100644 --- a/source/integrations.txt +++ b/source/integrations.txt @@ -1,8 +1,8 @@ .. _java-integrations: -=================== -Driver Integrations -=================== +======================== +Third-Party Integrations +======================== .. facet:: :name: genre diff --git a/source/logging-monitoring.txt b/source/logging-monitoring.txt new file mode 100644 index 000000000..af9de0f1b --- /dev/null +++ b/source/logging-monitoring.txt @@ -0,0 +1,14 @@ +====================== +Logging and Monitoring +====================== + +.. meta:: + :description: Learn how to use the {+driver-long+} logging and monitoring tools. + +.. toctree:: + :titlesonly: + :maxdepth: 1 + + Logging + Monitoring + Change Streams \ No newline at end of file diff --git a/source/fundamentals/crud/read-operations/change-streams.txt b/source/logging-monitoring/change-streams.txt similarity index 100% rename from source/fundamentals/crud/read-operations/change-streams.txt rename to source/logging-monitoring/change-streams.txt diff --git a/source/fundamentals/logging.txt b/source/logging-monitoring/logging.txt similarity index 99% rename from source/fundamentals/logging.txt rename to source/logging-monitoring/logging.txt index 3b11c9bc4..d7dc66097 100644 --- a/source/fundamentals/logging.txt +++ b/source/logging-monitoring/logging.txt @@ -38,7 +38,7 @@ You will learn how to: This guide shows how to record events in the driver. If you would like to learn how to use information about the activity of the driver in code, consider reading our -:doc:`guide on monitoring `. +:doc:`guide on monitoring `. Set Up a Logger --------------- diff --git a/source/fundamentals/monitoring.txt b/source/logging-monitoring/monitoring.txt similarity index 99% rename from source/fundamentals/monitoring.txt rename to source/logging-monitoring/monitoring.txt index 33d17e71e..2d784bbbd 100644 --- a/source/fundamentals/monitoring.txt +++ b/source/logging-monitoring/monitoring.txt @@ -37,7 +37,7 @@ In this guide you will learn how to perform these tasks: This guide shows how to use information about the activity of the driver in code. If you would like to learn how to record events in the driver, -consider reading our :doc:`guide on logging `. +consider reading our :doc:`guide on logging `. .. _monitoring-monitor-events: diff --git a/source/reference.txt b/source/reference.txt new file mode 100644 index 000000000..3380ae0db --- /dev/null +++ b/source/reference.txt @@ -0,0 +1,15 @@ +========= +Reference +========= + +.. meta:: + :description: Learn about versioning in the {+driver-long+}. + +.. toctree:: + :titlesonly: + :maxdepth: 1 + + Release Notes + Compatibility + Upgrade + Migrate from the Legacy API \ No newline at end of file diff --git a/source/compatibility.txt b/source/reference/compatibility.txt similarity index 100% rename from source/compatibility.txt rename to source/reference/compatibility.txt diff --git a/source/legacy.txt b/source/reference/legacy.txt similarity index 100% rename from source/legacy.txt rename to source/reference/legacy.txt diff --git a/source/upgrade.txt b/source/reference/upgrade.txt similarity index 100% rename from source/upgrade.txt rename to source/reference/upgrade.txt diff --git a/source/whats-new.txt b/source/reference/whats-new.txt similarity index 100% rename from source/whats-new.txt rename to source/reference/whats-new.txt diff --git a/source/security.txt b/source/security.txt new file mode 100644 index 000000000..4414a7ffb --- /dev/null +++ b/source/security.txt @@ -0,0 +1,17 @@ +======== +Security +======== + +.. meta:: + :description: Learn how to use security features with the {+driver-long+}. + +.. toctree:: + :titlesonly: + :maxdepth: 1 + + Authentication + Enterprise Authentication + In-Use Encryption + TLS/SSL + SOCKS5 Proxy + Validate Driver Artifact Signatures \ No newline at end of file diff --git a/source/fundamentals/auth.txt b/source/security/auth.txt similarity index 99% rename from source/fundamentals/auth.txt rename to source/security/auth.txt index 0d8630ef4..bad70bdc3 100644 --- a/source/fundamentals/auth.txt +++ b/source/security/auth.txt @@ -574,4 +574,4 @@ mechanism: For additional information on configuring your application to use certificates as well as TLS/SSL options, see our -:doc:`TLS/SSL guide `. \ No newline at end of file +:doc:`TLS/SSL guide `. \ No newline at end of file diff --git a/source/fundamentals/encrypt-fields.txt b/source/security/encrypt-fields.txt similarity index 100% rename from source/fundamentals/encrypt-fields.txt rename to source/security/encrypt-fields.txt diff --git a/source/fundamentals/enterprise-auth.txt b/source/security/enterprise-auth.txt similarity index 100% rename from source/fundamentals/enterprise-auth.txt rename to source/security/enterprise-auth.txt diff --git a/source/fundamentals/connection/socks.txt b/source/security/socks.txt similarity index 100% rename from source/fundamentals/connection/socks.txt rename to source/security/socks.txt diff --git a/source/fundamentals/connection/tls.txt b/source/security/tls.txt similarity index 100% rename from source/fundamentals/connection/tls.txt rename to source/security/tls.txt diff --git a/source/validate-signatures.txt b/source/security/validate-signatures.txt similarity index 100% rename from source/validate-signatures.txt rename to source/security/validate-signatures.txt diff --git a/source/usage-examples.txt b/source/usage-examples.txt index 208b025ec..f35cc0ecc 100644 --- a/source/usage-examples.txt +++ b/source/usage-examples.txt @@ -69,4 +69,4 @@ to learn how to allow connections to your instance of Atlas and to find the ```` with the IP address or URL of your instance. For more information about connecting to your MongoDB instance, see our -:doc:`Connection Guide `. +:doc:`Connection Guide `. diff --git a/source/usage-examples/find.txt b/source/usage-examples/find.txt index ee9c93969..742732ba5 100644 --- a/source/usage-examples/find.txt +++ b/source/usage-examples/find.txt @@ -13,7 +13,7 @@ the collection. If you do not include a filter, MongoDB returns all the documents in the collection. For more information about querying MongoDB with the Java driver, see our -:doc:`guide on Querying Documents `. +:doc:`guide on Querying Documents `. You can also chain methods to the ``find()`` method such as ``sort()`` which organizes the matched documents in a specified order and @@ -21,9 +21,9 @@ organizes the matched documents in a specified order and returned documents. For more information about the ``sort()`` method, see our -:doc:`guide on Sorting `. +:doc:`guide on Sorting `. For more information about the ``projection()`` method, see our -:doc:`guide on Projections ` +:doc:`guide on Projections ` The ``find()`` method returns an instance of ``FindIterable``, a class that offers several methods to access, organize, and traverse the results. diff --git a/source/usage-examples/findOne.txt b/source/usage-examples/findOne.txt index ca275c2ee..7270c2f00 100644 --- a/source/usage-examples/findOne.txt +++ b/source/usage-examples/findOne.txt @@ -14,16 +14,16 @@ include a filter, MongoDB returns all the documents in the collection. The ``first()`` method returns the first matching document. For more information about querying MongoDB with the Java driver, see our -:doc:`guide on Querying Documents `. +:doc:`guide on Querying Documents `. You can also chain other methods to the ``find()`` method such as ``sort()`` which organizes the matched documents in a specified order, and ``projection()`` which configures the fields included in the returned documents. For more information about the ``sort()`` method, see our -:doc:`guide on Sorting `. +:doc:`guide on Sorting `. For more information about the ``projection()`` method, see our -:doc:`guide on Projections ` +:doc:`guide on Projections ` The ``find()`` method returns an instance of ``FindIterable``, a class that offers several methods to access, organize, and traverse the results. diff --git a/source/usage-examples/updateMany.txt b/source/usage-examples/updateMany.txt index ce791efec..8385a1451 100644 --- a/source/usage-examples/updateMany.txt +++ b/source/usage-examples/updateMany.txt @@ -70,7 +70,7 @@ We use the ``Updates`` builder, a factory class that contains static helper methods to construct the update document. While you can pass an update document instead of using the builder, the builder provides type checking and simplified syntax. Read our -:doc:`guide on Updates ` in the Builders +:doc:`guide on Updates ` in the Builders section for more information. .. include:: /includes/connect-guide-note.rst diff --git a/source/usage-examples/updateOne.txt b/source/usage-examples/updateOne.txt index e8ce7eba2..f2696177f 100644 --- a/source/usage-examples/updateOne.txt +++ b/source/usage-examples/updateOne.txt @@ -69,7 +69,7 @@ We use the ``Updates`` builder, a factory class that contains static helper methods, to construct the update document. While you can pass an update document instead of using the builder, the builder provides type checking and simplified syntax. For more information about the ``Updates`` builder, see our -:doc:`guide on the Updates builder `. +:doc:`guide on the Updates builder `. .. include:: /includes/connect-guide-note.rst From 8130036d8a68b1ab5cf2dd770097beb38734560d Mon Sep 17 00:00:00 2001 From: Rea Rustagi <85902999+rustagir@users.noreply.github.com> Date: Wed, 9 Apr 2025 09:26:43 -0400 Subject: [PATCH 33/37] Update upgrade.txt --- source/reference/upgrade.txt | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/source/reference/upgrade.txt b/source/reference/upgrade.txt index 57bb7b6c2..08a1f8753 100644 --- a/source/reference/upgrade.txt +++ b/source/reference/upgrade.txt @@ -435,6 +435,16 @@ end-of-life (EOL). To learn more about the MongoDB support for EOL products, see the `Legacy Support Policy `__. +.. _java-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-server-release-change-v4.8: Version 4.8 Server Release Support Changes From 34adebd785bbf6274a6359f23f8380e8acb66825 Mon Sep 17 00:00:00 2001 From: rustagir Date: Tue, 22 Apr 2025 09:09:42 -0400 Subject: [PATCH 34/37] redirects for UEs + other fixes (cherry picked from commit 91dc6fae3e9678413b27972a97255e9dc7a5a016) (cherry picked from commit a2cd5903148c54c1054b2ffd2d66a60914121301) (cherry picked from commit 184cd3f1c4588ec5bb8369d805d3710bb5222b4e) (cherry picked from commit c891e4eb0b351815a67ee0a534a71650511dab2e) --- source/atlas-search.txt | 2 +- source/crud/collations.txt | 6 ++---- source/crud/gridfs.txt | 2 ++ 3 files changed, 5 insertions(+), 5 deletions(-) diff --git a/source/atlas-search.txt b/source/atlas-search.txt index a21049881..6cfbc27d1 100644 --- a/source/atlas-search.txt +++ b/source/atlas-search.txt @@ -18,4 +18,4 @@ Atlas Search :depth: 2 :class: singlecol -See :atlas:`Atlas Search ` in the MongoDB Atlas documentation. \ No newline at end of file +See :atlas:`Atlas Search ` in the MongoDB Atlas documentation. diff --git a/source/crud/collations.txt b/source/crud/collations.txt index 3cac66424..1c2d8dcd4 100644 --- a/source/crud/collations.txt +++ b/source/crud/collations.txt @@ -1,9 +1,9 @@ +.. _java-crud-collations: + ========== Collations ========== -.. default-domain:: mongodb - .. contents:: On this page :local: :backlinks: none @@ -65,7 +65,6 @@ order as shown below: coté côté - .. _collations-specify: How to Specify Collations @@ -536,4 +535,3 @@ see the following API Documentation: - `Accumulators <{+api+}/apidocs/mongodb-driver-core/com/mongodb/client/model/Accumulators.html>`__ - `Aggregates <{+api+}/apidocs/mongodb-driver-core/com/mongodb/client/model/Aggregates.html>`__ - `Sorts <{+api+}/apidocs/mongodb-driver-core/com/mongodb/client/model/Sorts.html>`__ - diff --git a/source/crud/gridfs.txt b/source/crud/gridfs.txt index bd47e7dc2..b98cfb28f 100644 --- a/source/crud/gridfs.txt +++ b/source/crud/gridfs.txt @@ -1,3 +1,5 @@ +.. _java-crud-gridfs: + ============================== Large File Storage with GridFS ============================== From a9c36b9dc4fe4ef4bb69f57fb8a6503e78709f98 Mon Sep 17 00:00:00 2001 From: "github-actions[bot]" <41898282+github-actions[bot]@users.noreply.github.com> Date: Fri, 25 Apr 2025 14:21:23 -0400 Subject: [PATCH 35/37] [Backport v5.3] DOCSP-48713 Update non-MongoDB credentials (#679) (#681) * [Backport v5.3] DOCSP-48713 Update non-MongoDB credentials * change db_password (cherry picked from commit 2ff9e66950e177713c780e1bc9c46931d1a14873) Co-authored-by: lindseymoore <71525840+lindseymoore@users.noreply.github.com> --- .../code-snippets/auth-credentials-gssapi-properties.rst | 2 +- .../code-snippets/auth-credentials-gssapi-subject-key.rst | 2 +- .../auth-credentials-gssapi-ticket-cache.rst | 2 +- .../code-snippets/auth-credentials-gssapi.rst | 2 +- .../fundamentals/code-snippets/auth-credentials-ldap.rst | 2 +- source/security/enterprise-auth.txt | 8 ++++---- 6 files changed, 9 insertions(+), 9 deletions(-) diff --git a/source/includes/fundamentals/code-snippets/auth-credentials-gssapi-properties.rst b/source/includes/fundamentals/code-snippets/auth-credentials-gssapi-properties.rst index f4ec395ce..44fa2e0de 100644 --- a/source/includes/fundamentals/code-snippets/auth-credentials-gssapi-properties.rst +++ b/source/includes/fundamentals/code-snippets/auth-credentials-gssapi-properties.rst @@ -1,5 +1,5 @@ .. code-block:: java - MongoCredential credential = MongoCredential.createGSSAPICredential(); + MongoCredential credential = MongoCredential.createGSSAPICredential(); credential = credential.withMechanismProperty(MongoCredential.SERVICE_NAME_KEY, "myService"); diff --git a/source/includes/fundamentals/code-snippets/auth-credentials-gssapi-subject-key.rst b/source/includes/fundamentals/code-snippets/auth-credentials-gssapi-subject-key.rst index a5c1da73c..bb8dac028 100644 --- a/source/includes/fundamentals/code-snippets/auth-credentials-gssapi-subject-key.rst +++ b/source/includes/fundamentals/code-snippets/auth-credentials-gssapi-subject-key.rst @@ -4,6 +4,6 @@ loginContext.login(); Subject subject = loginContext.getSubject(); - MongoCredential credential = MongoCredential.createGSSAPICredential(); + MongoCredential credential = MongoCredential.createGSSAPICredential(); credential = credential.withMechanismProperty(MongoCredential.JAVA_SUBJECT_KEY, subject); diff --git a/source/includes/fundamentals/code-snippets/auth-credentials-gssapi-ticket-cache.rst b/source/includes/fundamentals/code-snippets/auth-credentials-gssapi-ticket-cache.rst index b446e3987..7070930ed 100644 --- a/source/includes/fundamentals/code-snippets/auth-credentials-gssapi-ticket-cache.rst +++ b/source/includes/fundamentals/code-snippets/auth-credentials-gssapi-ticket-cache.rst @@ -3,7 +3,7 @@ /* all MongoClient instances sharing this instance of KerberosSubjectProvider will share a Kerberos ticket cache */ String myLoginContext = "myContext"; - MongoCredential credential = MongoCredential.createGSSAPICredential(); + MongoCredential credential = MongoCredential.createGSSAPICredential(); /* login context defaults to "com.sun.security.jgss.krb5.initiate" if unspecified in KerberosSubjectProvider */ credential = credential.withMechanismProperty(MongoCredential.JAVA_SUBJECT_PROVIDER_KEY, diff --git a/source/includes/fundamentals/code-snippets/auth-credentials-gssapi.rst b/source/includes/fundamentals/code-snippets/auth-credentials-gssapi.rst index 5f76050a4..0cb0795f9 100644 --- a/source/includes/fundamentals/code-snippets/auth-credentials-gssapi.rst +++ b/source/includes/fundamentals/code-snippets/auth-credentials-gssapi.rst @@ -1,6 +1,6 @@ .. code-block:: java - MongoCredential credential = MongoCredential.createGSSAPICredential(); + MongoCredential credential = MongoCredential.createGSSAPICredential(); MongoClient mongoClient = MongoClients.create( MongoClientSettings.builder() diff --git a/source/includes/fundamentals/code-snippets/auth-credentials-ldap.rst b/source/includes/fundamentals/code-snippets/auth-credentials-ldap.rst index d539843dc..a2b19de44 100644 --- a/source/includes/fundamentals/code-snippets/auth-credentials-ldap.rst +++ b/source/includes/fundamentals/code-snippets/auth-credentials-ldap.rst @@ -1,6 +1,6 @@ .. code-block:: java - MongoCredential credential = MongoCredential.createPlainCredential(, "$external", ); + MongoCredential credential = MongoCredential.createPlainCredential(, "$external", ); MongoClient mongoClient = MongoClients.create( MongoClientSettings.builder() diff --git a/source/security/enterprise-auth.txt b/source/security/enterprise-auth.txt index f6c15eda0..3dd449edb 100644 --- a/source/security/enterprise-auth.txt +++ b/source/security/enterprise-auth.txt @@ -63,7 +63,7 @@ principal name. The following code snippets show how to specify the authentication mechanism, using the following placeholders: -- ``username``: your URL-encoded principal name, such as ``"username%40REALM.ME"`` +- ``principal_username``: your URL-encoded principal name, such as ``"username%40REALM.ME"`` - ``hostname``: network address of your MongoDB deployment that your client can access - ``port``: port number of your MongoDB deployment @@ -92,7 +92,7 @@ mechanism: .. code-block:: java - MongoClient mongoClient = MongoClients.create("@:/?authSource=$external&authMechanism=GSSAPI"); + MongoClient mongoClient = MongoClients.create("@:/?authSource=$external&authMechanism=GSSAPI"); .. tab:: :tabid: MongoCredential @@ -151,7 +151,7 @@ You might need to specify one or more of the following additional .. code-block:: java - MongoClient mongoClient = MongoClients.create("@:/?authSource=$external&authMechanism=GSSAPI&authMechanismProperties=SERVICE_NAME:myService"); + MongoClient mongoClient = MongoClients.create("@:/?authSource=$external&authMechanism=GSSAPI&authMechanismProperties=SERVICE_NAME:myService"); .. tab:: :tabid: MongoCredential @@ -277,7 +277,7 @@ mechanism: .. code-block:: java - MongoClient mongoClient = MongoClients.create(":@:/?authSource=$external&authMechanism=PLAIN"); + MongoClient mongoClient = MongoClients.create(":@:/?authSource=$external&authMechanism=PLAIN"); .. tab:: :tabid: MongoCredential From c2f40fe1b6012ea930bb07ba3a48696a38701a2f Mon Sep 17 00:00:00 2001 From: Rachel Mackintosh <148898879+rachel-mack@users.noreply.github.com> Date: Tue, 27 May 2025 13:46:11 -0400 Subject: [PATCH 36/37] rename what's new (#698) (#701) --- config/redirects | 1 + source/index.txt | 6 +++--- source/reference.txt | 9 +++++++-- source/reference/legacy.txt | 2 +- source/reference/{whats-new.txt => release-notes.txt} | 7 ++++--- 5 files changed, 16 insertions(+), 9 deletions(-) rename source/reference/{whats-new.txt => release-notes.txt} (99%) diff --git a/config/redirects b/config/redirects index 5373422cc..88042cc3a 100644 --- a/config/redirects +++ b/config/redirects @@ -69,3 +69,4 @@ raw: ${prefix}/master -> ${base}/upcoming/ [v5.0-master]: ${prefix}/${version}/quick-reference/ -> ${base}/${version}/getting-started/quick-reference/ [v5.0-master]: ${prefix}/${version}/fundamentals/enterprise-auth/ -> ${base}/${version}/security/enterprise-auth/ [v5.0-master]: ${prefix}/${version}/connection/socks/ -> ${base}/${version}/security/socks/ +[v5.0-*]: ${prefix}/${version}/whats-new/ -> ${base}/${version}/reference/release-notes/ diff --git a/source/index.txt b/source/index.txt index 74896d726..f4f7f91ea 100644 --- a/source/index.txt +++ b/source/index.txt @@ -69,11 +69,11 @@ Quick Reference See driver syntax examples for common MongoDB commands in the :ref:`Quick Reference ` section. -What's New ----------- +Release Notes +------------- For a list of new features and changes in each version, see the -:ref:`What's New ` section. +:ref:`Release Notes ` section. Usage Examples -------------- diff --git a/source/reference.txt b/source/reference.txt index 3380ae0db..6bdb9fd27 100644 --- a/source/reference.txt +++ b/source/reference.txt @@ -9,7 +9,12 @@ Reference :titlesonly: :maxdepth: 1 - Release Notes + Release Notes Compatibility Upgrade - Migrate from the Legacy API \ No newline at end of file + Migrate from the Legacy API + +- :ref:`Release Notes ` +- :ref:`Compatibility ` +- :ref:`Upgrade ` +- :ref:`Migrate from the Legacy API ` diff --git a/source/reference/legacy.txt b/source/reference/legacy.txt index d46411db7..3a0d88d1b 100644 --- a/source/reference/legacy.txt +++ b/source/reference/legacy.txt @@ -62,7 +62,7 @@ API include: - **Native POJO support**, which provides automatic or custom mapping between MongoDB documents and Java objects -To learn about more features of the current API, see :ref:`java-whats-new`. +To learn about more features of the current API, see :ref:`java-release-notes`. API Changes diff --git a/source/reference/whats-new.txt b/source/reference/release-notes.txt similarity index 99% rename from source/reference/whats-new.txt rename to source/reference/release-notes.txt index 569db101a..ef7fc4257 100644 --- a/source/reference/whats-new.txt +++ b/source/reference/release-notes.txt @@ -1,8 +1,9 @@ .. _java-whats-new: +.. _java-release-notes: -========== -What's New -========== +============= +Release Notes +============= .. facet:: :name: genre From d225eab48eac02429d11b962dc4645c8b5f0f1c0 Mon Sep 17 00:00:00 2001 From: rustagir Date: Wed, 28 May 2025 10:07:13 -0400 Subject: [PATCH 37/37] Redirects issue investigation (cherry picked from commit 4b69cfd0bf583ec471388ce0447478fb930c21d6) --- snooty.toml | 4 ++-- source/builders/sort.txt | 3 ++- source/crud/read-operations/sort.txt | 1 + source/crud/read-operations/text.txt | 4 ++-- source/databases-collections.txt | 2 ++ source/{getting-started.txt => get-started.txt} | 8 ++++---- .../{getting-started => get-started}/quick-reference.txt | 0 source/index.txt | 6 +++--- 8 files changed, 16 insertions(+), 12 deletions(-) rename source/{getting-started.txt => get-started.txt} (96%) rename source/{getting-started => get-started}/quick-reference.txt (100%) diff --git a/snooty.toml b/snooty.toml index 4c6c9829b..b4b5dfff1 100644 --- a/snooty.toml +++ b/snooty.toml @@ -7,13 +7,13 @@ intersphinx = [ ] toc_landing_pages = [ - "/getting-started", + "/get-started", "/connection", "/crud", "/aggregation", "/builders", "/data-formats", - "/api-documentation" + "/api-documentation", ] sharedinclude_root = "https://raw.githubusercontent.com/10gen/docs-shared/main/" diff --git a/source/builders/sort.txt b/source/builders/sort.txt index f73f01b2e..720d2c07c 100644 --- a/source/builders/sort.txt +++ b/source/builders/sort.txt @@ -174,7 +174,8 @@ closely a search result matches your search string. To specify a sort by the text score of a text search, use the ``Sorts.metaTextScore()`` static factory method. For a detailed example showing how to specify sort criteria using the ``Sorts.metaTextScore()`` method, see -:ref:`the text search section of our sorting fundamentals guide `. +:ref:`the text search section of our sorting fundamentals guide +`. For more information, see the `Sorts class <{+api+}/apidocs/mongodb-driver-core/com/mongodb/client/model/Sorts.html>`__ diff --git a/source/crud/read-operations/sort.txt b/source/crud/read-operations/sort.txt index b0cccdbad..b10b5e801 100644 --- a/source/crud/read-operations/sort.txt +++ b/source/crud/read-operations/sort.txt @@ -304,6 +304,7 @@ in the following order: {"_id": 3, "letter": "a", "food": "maple syrup"} {"_id": 5, "letter": "a", "food": "milk and cookies"} +.. _java-sync-sorts-crud-text-search: .. _sorts-crud-text-search: Text Search diff --git a/source/crud/read-operations/text.txt b/source/crud/read-operations/text.txt index 3618366f7..289398744 100644 --- a/source/crud/read-operations/text.txt +++ b/source/crud/read-operations/text.txt @@ -31,7 +31,7 @@ text searches: - Search Text with Terms Excluded If you want to sort your text search results, see the :ref:`Text Search -` section of our Sort Results guide. +` section of our Sort Results guide. Sample Documents ~~~~~~~~~~~~~~~~ @@ -92,7 +92,7 @@ When you execute the ``find()`` method, MongoDB runs a text search on all the fields indexed with the text index on the collection. MongoDB returns documents that contain one or more of the search terms and a relevance score for each result. For more information about relevance -scores, see the :ref:`Text Search ` section in +scores, see the :ref:`Text Search ` section in our Sort Results guide. Specify Options diff --git a/source/databases-collections.txt b/source/databases-collections.txt index 30ffcedbb..e6c21a808 100644 --- a/source/databases-collections.txt +++ b/source/databases-collections.txt @@ -1,3 +1,5 @@ +.. _java-sync-databases-collections: + ========================= Databases and Collections ========================= diff --git a/source/getting-started.txt b/source/get-started.txt similarity index 96% rename from source/getting-started.txt rename to source/get-started.txt index f76d668b1..3b2f5feb4 100644 --- a/source/getting-started.txt +++ b/source/get-started.txt @@ -1,8 +1,8 @@ .. _java-sync-quickstart: -=============== -Getting Started -=============== +================================ +Get Started with the Java Driver +================================ .. facet:: :name: genre @@ -21,7 +21,7 @@ Getting Started :titlesonly: :maxdepth: 1 - Quick Reference + Quick Reference Introduction ------------ diff --git a/source/getting-started/quick-reference.txt b/source/get-started/quick-reference.txt similarity index 100% rename from source/getting-started/quick-reference.txt rename to source/get-started/quick-reference.txt diff --git a/source/index.txt b/source/index.txt index f4f7f91ea..40cf54f55 100644 --- a/source/index.txt +++ b/source/index.txt @@ -18,10 +18,10 @@ MongoDB Java Driver :titlesonly: :maxdepth: 1 - Getting Started + Get Started Connect CRUD Operations - Databases and Collations + Databases & Collections Aggregation Builders Data Formats @@ -29,7 +29,7 @@ MongoDB Java Driver Run a Command Atlas Search Atlas Vector Search - Logging and Monitoring + Logging & Monitoring Security Third-Party Integrations Reference