From 59b3a526b752f66e1c09bf97d84bc41b279958f5 Mon Sep 17 00:00:00 2001 From: Chris Cho Date: Thu, 10 Aug 2023 17:55:32 -0400 Subject: [PATCH 1/7] DOCSP-26370: FAQ entry for MongoSecurityException --- source/faq.txt | 128 +++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 128 insertions(+) diff --git a/source/faq.txt b/source/faq.txt index 4b1b3c2af..9c17d56ec 100644 --- a/source/faq.txt +++ b/source/faq.txt @@ -148,6 +148,134 @@ When ``MongoClient.close()`` is called by any thread, the driver closes all idle sockets and closes all sockets that are in use as they are returned to the pool. +How do I prevent the "java.lang.NoClassDefFoundError: com/mongodb/MongoClient" error? +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +You may encounter a ``java.lang.NoClassDefFoundError`` exception when your +Java runtime environment cannot locate a class file at runtime. When you +attempt to run application code that uses the {+driver-long+}, you must include +the appropriate driver JAR files on the classpath. + +If you receive this error after adding the {+driver-short+} JAR files to +your classpath, check the following items in your environment: + +- The JAR files exist in the locations specified by the classpath. +- The classpath syntax is correct. +- If you define the classpath in an environment variable, the Java runtime + environment uses that variable. +- If you use a dependency manager, it does not report any unresolvable conflicts. + +.. tip:: + + This error contains the package and class name, which can help you identify + which driver JAR may be missing from your classpath. To locate the + driver JAR that the error refers to, check each of the entries in the + :ref:`API documentation `. + + +How do I prevent the "com.mongodb.MongoSecurityException" error? +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Your application may throw this exception if you attempt to connect to +a MongoDB deployment by using invalid or incorrectly formatted credentials. + +To find the potential cause of this error, verify that you properly +specified the following items: + +- The connection URI corresponds to the correct MongoDB deployment. + To learn more about setting your connection URI, see :ref:`connection-uri`. + +- The credentials, such as the username and password, for the authentication + mechanism that you specified are correct. To learn how to specify your + credentials, see :ref:`authentication-mechanisms` or + :ref:`enterprise-authentication-mechanisms`. + +- The database user has sufficient permissions to connect. If your deployment + is hosted on MongoDB Atlas, see + `View Database Users and Certificates `__ + to learn how to view database user permissions. + +- The name of the authentication database is correct. To learn how to specify + your authentication database, see :ref:`java-connection-admin` + in the Connection Troubleshooting guide, or view the example for your + authentication mechanism in the :ref:`authentication-mechanisms` or + :ref:`enterprise-authentication-mechanisms` guide. + +How do I prevent the "IllegalArgumentException: Invalid BSON field name" error? +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Your application may throw this exception if you pass an incorrectly formatted +document to an operation and you are using a driver version v4.7 or earlier. + +.. note:: + + In driver versions v4.8 and later, this error message was replaced by one + that includes more specific details on what was incorrectly formatted. + +For example, the driver throws this error when you call an update operation +and incorrectly omit the update operator as shown in the following code +example: + +.. code-block:: java + :emphasize-lines: 4 + :copyable: false + + // incorrectly formatted update document + collection.updateOne( + new Document().append("name", "fizz"), + new Document().append("name", "buzz") + ); + +To avoid this error, use the builder class for the appropriate operation. +The driver offers builder classes to create syntactically correct BSON for +MongoDB operations. The prior example can be correctly expressed using +the builder classes as shown in the following code example: + +.. code-block:: java + :emphasize-lines: 7 + :copyable: false + + // Builder class imports + import static com.mongodb.client.model.Filters.*; + import static com.mongodb.client.model.Updates.*; + + // ... + + collection.updateOne(eq("name", "fizz"), set("name", "buzz")); + +To learn more about the available builders classes, see the :ref:`` documentation. + + +How do I prevent the "IllegalStateException: state should be: open" error? +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +You may encounter this exception if you call an operation on a ``MongoClient`` +instance that closed its connections to MongoDB. Once the ``close()`` method +is called on the ``MongoClient``, any further operation calls on that instance +throw this exception. + +To avoid this exception, do not call operations on ``MongoClient`` instance +after any code that calls ``close()`` on it. + +.. tip:: + + The code that closes the ``MongoClient`` instance may be difficult to + locate in certain cases. To locate potential sources of this exception, + search for the following cases: + + - Calls to ``close()`` on a ``MongoClient`` instance + - Operation calls on a ``MongoClient`` instance that are outside the scope + of the try-with-resources statement in which the ``MongoClient`` is + declared + + If your application uses a framework to manage the ``MongoClient`` + such as Spring Boot, check the documentation of the framework to locate the + best practices for managing the connection behavior. + + To learn more about accessing MongoDB from Spring Boot, see + `Spring Boot and MongoDB `__. + + POJOs ----- From eab2bd69e989b25c67c251e0fa50729a85a273de Mon Sep 17 00:00:00 2001 From: Chris Cho Date: Thu, 10 Aug 2023 18:06:31 -0400 Subject: [PATCH 2/7] tweaks --- source/faq.txt | 14 +++++--------- 1 file changed, 5 insertions(+), 9 deletions(-) diff --git a/source/faq.txt b/source/faq.txt index 55457072b..d71c26dbc 100644 --- a/source/faq.txt +++ b/source/faq.txt @@ -188,16 +188,12 @@ specified the following items: credentials, see :ref:`authentication-mechanisms` or :ref:`enterprise-authentication-mechanisms`. -- The database user has sufficient permissions to connect. If your deployment - is hosted on MongoDB Atlas, see - `View Database Users and Certificates `__ - to learn how to view database user permissions. - -- The name of the authentication database is correct. To learn how to specify +- The name of the authentication database is correct. To learn how to specify your authentication database, see :ref:`java-connection-admin` - in the Connection Troubleshooting guide, or view the example for your - authentication mechanism in the :ref:`authentication-mechanisms` or - :ref:`enterprise-authentication-mechanisms` guide. + in the Connection Troubleshooting guide, or view the code example that + corresponds to your authentication mechanism in the + :ref:`authentication-mechanisms` or :ref:`enterprise-authentication-mechanisms` + guide. How do I prevent the "IllegalArgumentException: Invalid BSON field name" error? ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ From 3435a4f41a66352805cabba27df91dfc600d3631 Mon Sep 17 00:00:00 2001 From: Chris Cho Date: Fri, 11 Aug 2023 10:11:52 -0400 Subject: [PATCH 3/7] edits for conciseness --- source/faq.txt | 19 ++++++++----------- 1 file changed, 8 insertions(+), 11 deletions(-) diff --git a/source/faq.txt b/source/faq.txt index d71c26dbc..7d7302a86 100644 --- a/source/faq.txt +++ b/source/faq.txt @@ -175,25 +175,22 @@ How do I prevent the "com.mongodb.MongoSecurityException" error? ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Your application may throw this exception if you attempt to connect to -a MongoDB deployment by using invalid or incorrectly formatted credentials. +a MongoDB deployment by specifying invalid or incorrectly formatted credentials. -To find the potential cause of this error, verify that you properly -specified the following items: +To find the potential cause of this error, verify the following items: - The connection URI corresponds to the correct MongoDB deployment. To learn more about setting your connection URI, see :ref:`connection-uri`. -- The credentials, such as the username and password, for the authentication - mechanism that you specified are correct. To learn how to specify your - credentials, see :ref:`authentication-mechanisms` or - :ref:`enterprise-authentication-mechanisms`. +- The credentials for the authentication mechanism that you specified are + correct. To learn how to specify your credentials, see + :ref:`authentication-mechanisms` or :ref:`enterprise-authentication-mechanisms`. - The name of the authentication database is correct. To learn how to specify your authentication database, see :ref:`java-connection-admin` - in the Connection Troubleshooting guide, or view the code example that - corresponds to your authentication mechanism in the - :ref:`authentication-mechanisms` or :ref:`enterprise-authentication-mechanisms` - guide. + in the Connection Troubleshooting guide. You can view code examples for + each authentication mechanism in the :ref:`authentication-mechanisms` and + :ref:`enterprise-authentication-mechanisms` guides. How do I prevent the "IllegalArgumentException: Invalid BSON field name" error? ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ From 56956d4a3181c2f0ec03bbea0d83b095e75deb7c Mon Sep 17 00:00:00 2001 From: Chris Cho Date: Fri, 11 Aug 2023 10:21:24 -0400 Subject: [PATCH 4/7] conform more closely to other FAQ entries --- source/faq.txt | 12 +++++++----- 1 file changed, 7 insertions(+), 5 deletions(-) diff --git a/source/faq.txt b/source/faq.txt index 7d7302a86..d22b983ac 100644 --- a/source/faq.txt +++ b/source/faq.txt @@ -177,17 +177,19 @@ How do I prevent the "com.mongodb.MongoSecurityException" error? Your application may throw this exception if you attempt to connect to a MongoDB deployment by specifying invalid or incorrectly formatted credentials. -To find the potential cause of this error, verify the following items: +If you receive this error when you attempt to connect to a MongoDB deployment, +check the following items in your code: - The connection URI corresponds to the correct MongoDB deployment. To learn more about setting your connection URI, see :ref:`connection-uri`. - The credentials for the authentication mechanism that you specified are - correct. To learn how to specify your credentials, see - :ref:`authentication-mechanisms` or :ref:`enterprise-authentication-mechanisms`. + correct. To learn how to specify your credentials, see the + :ref:`authentication-mechanisms` and :ref:`enterprise-authentication-mechanisms` + guides. -- The name of the authentication database is correct. To learn how to specify - your authentication database, see :ref:`java-connection-admin` +- The name of the authentication database you specified is correct. To learn + how to specify your authentication database, see :ref:`java-connection-admin` in the Connection Troubleshooting guide. You can view code examples for each authentication mechanism in the :ref:`authentication-mechanisms` and :ref:`enterprise-authentication-mechanisms` guides. From ecd1d54680d03014cac5fa7a4c67899bd38d43ef Mon Sep 17 00:00:00 2001 From: Chris Cho Date: Fri, 11 Aug 2023 10:47:29 -0400 Subject: [PATCH 5/7] restructure --- source/faq.txt | 11 +++++++---- 1 file changed, 7 insertions(+), 4 deletions(-) diff --git a/source/faq.txt b/source/faq.txt index d22b983ac..dd1cd9e46 100644 --- a/source/faq.txt +++ b/source/faq.txt @@ -189,10 +189,13 @@ check the following items in your code: guides. - The name of the authentication database you specified is correct. To learn - how to specify your authentication database, see :ref:`java-connection-admin` - in the Connection Troubleshooting guide. You can view code examples for - each authentication mechanism in the :ref:`authentication-mechanisms` and - :ref:`enterprise-authentication-mechanisms` guides. + how to set up the users and roles for your MongoDB deployment, see + `Manage Users and Roles `__ + in the Server documentation. + +For {+driver-short+} code examples of specifying credentials for +authentication mechanisms, see the :ref:`authentication-mechanisms` and +:ref:`enterprise-authentication-mechanisms` guides. How do I prevent the "IllegalArgumentException: Invalid BSON field name" error? ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ From df9c6f91fa41c39b587441b42722b90a6db357e7 Mon Sep 17 00:00:00 2001 From: Chris Cho Date: Fri, 11 Aug 2023 10:57:36 -0400 Subject: [PATCH 6/7] remove repeated info --- source/faq.txt | 4 ---- 1 file changed, 4 deletions(-) diff --git a/source/faq.txt b/source/faq.txt index dd1cd9e46..0c766757e 100644 --- a/source/faq.txt +++ b/source/faq.txt @@ -193,10 +193,6 @@ check the following items in your code: `Manage Users and Roles `__ in the Server documentation. -For {+driver-short+} code examples of specifying credentials for -authentication mechanisms, see the :ref:`authentication-mechanisms` and -:ref:`enterprise-authentication-mechanisms` guides. - How do I prevent the "IllegalArgumentException: Invalid BSON field name" error? ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ From f35a1c035dca5678e05e37923a04ca2472a556a6 Mon Sep 17 00:00:00 2001 From: Chris Cho Date: Fri, 11 Aug 2023 17:35:21 -0400 Subject: [PATCH 7/7] PRR fixes --- source/faq.txt | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/source/faq.txt b/source/faq.txt index 0c766757e..db7a7f087 100644 --- a/source/faq.txt +++ b/source/faq.txt @@ -174,8 +174,8 @@ your classpath, check the following items in your environment: How do I prevent the "com.mongodb.MongoSecurityException" error? ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Your application may throw this exception if you attempt to connect to -a MongoDB deployment by specifying invalid or incorrectly formatted credentials. +Your application might throw this exception if you specify invalid or +incorrectly formatted credentials when connecting to a MongoDB deployment. If you receive this error when you attempt to connect to a MongoDB deployment, check the following items in your code: @@ -188,15 +188,15 @@ check the following items in your code: :ref:`authentication-mechanisms` and :ref:`enterprise-authentication-mechanisms` guides. -- The name of the authentication database you specified is correct. To learn - how to set up the users and roles for your MongoDB deployment, see +- The name of the authentication database that you specified is correct. To + learn how to set up the users and roles for your MongoDB deployment, see `Manage Users and Roles `__ in the Server documentation. How do I prevent the "IllegalArgumentException: Invalid BSON field name" error? ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Your application may throw this exception if you pass an incorrectly formatted +Your application might throw this exception if you pass an incorrectly formatted document to an operation and you are using a driver version v4.7 or earlier. .. note::