diff --git a/snooty.toml b/snooty.toml index 82b743182..c0aa5de6f 100644 --- a/snooty.toml +++ b/snooty.toml @@ -7,7 +7,7 @@ intersphinx = [ ] toc_landing_pages = [ - "/getting-started", + "/get-started", "/connection", "/crud", "/crud/builders", diff --git a/source/get-started.txt b/source/get-started.txt new file mode 100644 index 000000000..4dec6ef26 --- /dev/null +++ b/source/get-started.txt @@ -0,0 +1,52 @@ +.. _java-get-started: + +================================ +Get Started with the Java Driver +================================ + +.. facet:: + :name: genre + :values: tutorial + +.. meta:: + :description: Learn how to create an app to connect to MongoDB deployment by using the {+driver-short+}. + :keywords: quick start, tutorial, basics + +.. toctree:: + + Download & Install + Create a Deployment + Create a Connection String + Connect to MongoDB + Next Steps + Databases & Collections + Integrations + +Overview +-------- + +The {+driver-short+} is a synchronous API that you can use to interact with MongoDB +from your Java application. This guide shows you how to create an application that +uses the {+driver-short+} to connect to a MongoDB cluster hosted on MongoDB Atlas +and query data in your cluster. + +.. tip:: + + :atlas:`MongoDB Atlas ` is a fully managed cloud database service + that hosts your MongoDB deployments. You can create your own free (no credit card required) + MongoDB Atlas deployment by following the steps in this guide. + +Follow this tutorial to connect a sample Java application to a MongoDB Atlas +deployment. The tutorial includes the following sections: + +- :ref:`java-get-started-download-and-install`: Learn how to install + the {+driver-short+}. +- :ref:`java-get-started-create-deployment`: Learn how to create + a free MongoDB deployment on Atlas. +- :ref:`java-get-started-connection-string`: Learn how to retrieve + your Atlas deployment's connection string. +- :ref:`java-connect-to-mongodb`: Learn how to create an application + that connects to MongoDB and queries data stored in your deployment. + +If you prefer to connect to MongoDB using a different driver or +programming language, see our :driver:`list of official drivers <>`. \ No newline at end of file diff --git a/source/get-started/connect-to-mongodb.txt b/source/get-started/connect-to-mongodb.txt new file mode 100644 index 000000000..63c215b95 --- /dev/null +++ b/source/get-started/connect-to-mongodb.txt @@ -0,0 +1,52 @@ +.. _java-connect-to-mongodb: + +================== +Connect to MongoDB +================== + +.. facet:: + :name: genre + :values: tutorial + +.. meta:: + :keywords: test connection, runnable, code example + +After retrieving the connection string for your MongoDB Atlas deployment, +you can connect to the deployment from your Java application and query +the Atlas sample datasets. + +.. procedure:: + :style: connected + + .. step:: Create your Java application file + + In your project's base package directory, create a file called + ``QuickStart.java``. Copy and paste the following code into this file, + which queries the ``movies`` collection in the ``sample_mflix`` database: + + .. literalinclude:: /includes/get-started/code-snippets/QuickStart.java + :start-after: begin QuickStart + :end-before: end QuickStart + :language: java + :dedent: + + .. step:: Assign the connection string + + Replace the ```` placeholder with the connection string + that you copied from the :ref:`java-get-started-connection-string` step of this + guide. + + .. step:: Run your Java application + + Run your application in your IDE or your shell. Your output + contains details about the retrieved movie document: + + .. include:: /includes/get-started/query-output.rst + + .. include:: /includes/get-started/jdk-tls-issue.rst + +After you complete these steps, you have a Java application that +connects to your MongoDB deployment, runs a query on the sample +data, and returns a matching document. + +.. include:: /includes/get-started/quickstart-troubleshoot.rst diff --git a/source/get-started/connection-string.txt b/source/get-started/connection-string.txt new file mode 100644 index 000000000..d5e1dc250 --- /dev/null +++ b/source/get-started/connection-string.txt @@ -0,0 +1,53 @@ +.. _java-get-started-connection-string: + +========================== +Create a Connection String +========================== + +You can connect to your MongoDB deployment by providing a +**connection URI**, also called a *connection string*, which +instructs the driver on how to connect to a MongoDB deployment +and how to behave while connected. + +The connection string includes the hostname or IP address and +port of your deployment, the authentication mechanism, user credentials +when applicable, and connection options. + +.. procedure:: + :style: connected + + .. step:: Find your MongoDB Atlas connection string + + To retrieve your connection string for the deployment that + you created in the :ref:`previous step `, + log into your Atlas account and navigate to the + :guilabel:`Clusters` section. Click the :guilabel:`Connect` button + for your new deployment, as shown in the following screenshot: + + .. figure:: /includes/figures/atlas_connection_connect_cluster.png + :alt: The connect button in the clusters section of the Atlas UI + + Then, proceed to the :guilabel:`Connect your application` section. Select + "Java" from the :guilabel:`Driver` selection menu and the version + that best matches the version you installed from the :guilabel:`Version` + selection menu. + + .. step:: Copy your connection string + + Click the button on the right of the connection string to copy it to + your clipboard, as shown in the following screenshot: + + .. figure:: /includes/figures/atlas_connection_copy_uri_java.png + :alt: The connection string copy button in the Atlas UI + + .. step:: Edit your connection string placeholders + + Paste your connection string into a file in your preferred text editor + and save this file to a safe location for later use. In your connection + string, replace the ```` and ```` placeholders with + your database user's username and password. + +After completing these steps, you have a connection string that +contains your database username and password. + +.. include:: /includes/get-started/quickstart-troubleshoot.rst \ No newline at end of file diff --git a/source/get-started/create-deployment.txt b/source/get-started/create-deployment.txt new file mode 100644 index 000000000..adf078dbe --- /dev/null +++ b/source/get-started/create-deployment.txt @@ -0,0 +1,29 @@ +.. _java-get-started-create-deployment: + +=========================== +Create a MongoDB Deployment +=========================== + +You can create a free tier MongoDB deployment on MongoDB Atlas +to store and manage your data. MongoDB Atlas hosts and manages +your MongoDB database in the cloud. + +.. procedure:: + :style: connected + + .. step:: Create a free MongoDB deployment on Atlas + + Complete the :atlas:`Get Started with Atlas ` + guide to set up a new Atlas account and a free tier MongoDB deployment. + Ensure that you :atlas:`load sample data ` and + :atlas:`add your IP address ` to the IP access + list. + + .. step:: Save your credentials + + After you create your database user, save that user's + username and password to a safe location for use in an upcoming step. + +After you complete these steps, you have a new free tier MongoDB +deployment on Atlas, database user credentials, and sample data loaded +in your database. \ No newline at end of file diff --git a/source/getting-started/databases-collections.txt b/source/get-started/databases-collections.txt similarity index 99% rename from source/getting-started/databases-collections.txt rename to source/get-started/databases-collections.txt index 873bf6a1f..cee793148 100644 --- a/source/getting-started/databases-collections.txt +++ b/source/get-started/databases-collections.txt @@ -1,3 +1,5 @@ +.. _java-db-coll: + ========================= Databases and Collections ========================= diff --git a/source/get-started/download-and-install.txt b/source/get-started/download-and-install.txt new file mode 100644 index 000000000..25809997f --- /dev/null +++ b/source/get-started/download-and-install.txt @@ -0,0 +1,61 @@ +.. _java-get-started-download-and-install: + +==================== +Download and Install +==================== + +Complete the following steps to install the {+driver-short+} and +its dependencies in your development environment. + +.. procedure:: + :style: connected + + .. step:: Install the driver dependencies + + Before you begin this tutorial, ensure that you install + the following dependencies: + + - `JDK `__ + version 8 or later + - Integrated development environment (IDE), such as `IntelliJ IDEA `__ + or `Eclipse `__ + + .. note:: + + This tutorial shows how to install the {+driver-short+} by using + Maven or Gradle in an IDE. If you do not use an IDE, visit `Building Maven + `__ + or `Creating New Gradle Builds `__ + to learn how to set up your project. + + .. step:: Install the {+driver-short+} + + In your IDE, create a new `Maven `__ or `Gradle `__ + project. If you use Maven, add the following code to your ``pom.xml`` dependencies list: + + .. code-block:: xml + + + + org.mongodb + mongodb-driver-sync + {+full-version+} + + + + If you use Gradle, add the following code to your ``build.gradle`` dependencies list: + + .. code-block:: groovy + + dependencies { + implementation 'org.mongodb:mongodb-driver-sync:{+full-version+}' + } + + After you configure your dependencies, ensure they are available to your + project by running your dependency manager and refreshing + the project in your IDE. + +After you complete these steps, you have a new project +and the driver dependencies installed. + +.. include:: /includes/get-started/quickstart-troubleshoot.rst \ No newline at end of file diff --git a/source/getting-started/integrations.txt b/source/get-started/integrations.txt similarity index 100% rename from source/getting-started/integrations.txt rename to source/get-started/integrations.txt diff --git a/source/get-started/next-steps.txt b/source/get-started/next-steps.txt new file mode 100644 index 000000000..8be4e1fb3 --- /dev/null +++ b/source/get-started/next-steps.txt @@ -0,0 +1,19 @@ +.. _java-get-started-next-steps: + +========== +Next Steps +========== + +Congratulations on completing the tutorial! + +In this tutorial, you created a {+driver-short+} application that +connects to a MongoDB deployment hosted on MongoDB Atlas +and retrieves a document that matches a query. + +You can continue to develop your sample application by +visiting the following guides: + +- :ref:`java-db-coll`: Learn more about interacting with + MongoDB databases and collections. +- :ref:`java-integrations`: Learn about the third-party + integrations that you can use with the {+driver-short+}. \ No newline at end of file diff --git a/source/getting-started.txt b/source/getting-started.txt deleted file mode 100644 index 9120522de..000000000 --- a/source/getting-started.txt +++ /dev/null @@ -1,144 +0,0 @@ -.. _java-sync-quickstart: - -=============== -Getting Started -=============== - -.. facet:: - :name: genre - :values: tutorial - -.. meta:: - :keywords: java sync, set up, runnable app - -.. contents:: On this page - :local: - :backlinks: none - :depth: 2 - :class: singlecol - -.. toctree:: - :titlesonly: - :maxdepth: 1 - - Quick Reference - Databases and Collections - Integrations - -Introduction ------------- - -.. include:: /includes/quick-start/overview.rst - -Set up Your Project -------------------- - -Install the Java Development Kit (JDK) -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -.. include:: /includes/quick-start/install-jdk.rst - -Create the Project -~~~~~~~~~~~~~~~~~~~ - -.. include:: /includes/quick-start/create-project.rst - -.. _add-mongodb-dependency: - -Add MongoDB as a Dependency -~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -If you are using `Maven `__, add the following to -your ``pom.xml`` dependencies list: - -.. include:: /includes/quick-start/maven-versioned.rst - -If you are using `Gradle `__, add the following to your -``build.gradle`` dependencies list: - -.. include:: /includes/quick-start/gradle-versioned.rst - -.. note:: - - 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 `__. - The {+driver-short+} requires downloading the JAR files for - the ``bson``, ``mongodb-driver-core``, and ``slf4j-api`` dependencies. - -Once you configure your dependencies, ensure they are available to your -project by running your dependency manager and refreshing -the project in your IDE. - -Create a MongoDB Cluster ------------------------- - -.. include:: /includes/quick-start/atlas-setup.rst - - -Query Your MongoDB Cluster from Your Application -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Next, create a file to contain your application called ``QuickStart.java`` -in the base package directory of 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. - -.. literalinclude:: /includes/quick-start/code-snippets/QuickStart.java - :start-after: begin QuickStart - :end-before: end QuickStart - :language: java - :dedent: - -.. include:: /includes/quick-start/query-output.rst - -.. include:: /includes/quick-start/jdk-tls-issue.rst - -After completing this step, you should have a working application that uses -the Java driver to connect to your MongoDB cluster, run a query on the -sample data, and print out the result. - -Working with POJOs (Optional) -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -In the previous section, you ran a query on a sample collection to retrieve -data in the map-like class ``Document``. In this section, you can learn to -use your own Plain Old Java Object (POJO) to store and retrieve data from -MongoDB. - -Create a file called ``Movie.java`` in the base package directory of your -project and add the following code for a class that includes the following -fields, setters, and getters: - -.. literalinclude:: /includes/quick-start/code-snippets/Movie.java - :start-after: begin moviePojo - :end-before: end moviePojo - :language: java - :dedent: - -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 -the password you created for your user that has **atlasAdmin** permissions: - -.. literalinclude:: /includes/quick-start/code-snippets/QuickStartPojoExample.java - :start-after: begin PojoQuickstart - :end-before: end PojoQuickstart - :language: java - :dedent: - -.. include:: /includes/quick-start/pojo-query-output.rst - -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 ` - -Next steps ----------- - -.. include:: /includes/quick-start/next-steps.rst diff --git a/source/getting-started/quick-reference.txt b/source/getting-started/quick-reference.txt deleted file mode 100644 index 14b84e5b1..000000000 --- a/source/getting-started/quick-reference.txt +++ /dev/null @@ -1,468 +0,0 @@ -.. _java-quick-reference: - -=============== -Quick Reference -=============== - - - -This page shows the driver syntax for several MongoDB commands and links to -their related reference and API documentation. - -.. list-table:: - :header-rows: 1 - :widths: 25 75 - - * - Command - - Syntax - - * - | **Find a Document** - | - | `API Documentation <{+api+}/apidocs/mongodb-driver-sync/com/mongodb/client/MongoCollection.html#find()>`__ - | :ref:`Usage Example ` - | :ref:`Fundamentals ` - - - .. io-code-block:: - :copyable: true - - .. input:: - :language: java - - coll.find(Filters.eq("title", "Hamlet")).first(); - - .. output:: - :language: json - :visible: false - - { title: 'Hamlet', type: 'movie', ... } - - * - | **Find Multiple Documents** - | - | `API Documentation <{+api+}/apidocs/mongodb-driver-sync/com/mongodb/client/MongoCollection.html#find(org.bson.conversions.Bson)>`__ - | :ref:`Usage Example ` - | :ref:`Fundamentals ` - - - .. io-code-block:: - :copyable: true - - .. input:: - :language: java - - coll.find(Filters.eq("year", 2005)) - - .. output:: - :language: json - :visible: false - - [ - { title: 'Christmas in Boston', year: 2005, ... }, - { title: 'Chicken Little', year: 2005, ... }, - ... - ] - - * - | **Insert a Document** - | - | `API Documentation <{+api+}/apidocs/mongodb-driver-sync/com/mongodb/client/MongoCollection.html#insertOne(TDocument)>`__ - | :ref:`Usage Example ` - | :ref:`Fundamentals ` - - - .. code-block:: java - :copyable: true - - coll.insertOne(new Document("title", "Jackie Robinson")); - - * - | **Insert Multiple Documents** - | - | `API Documentation <{+api+}/apidocs/mongodb-driver-sync/com/mongodb/client/MongoCollection.html#insertMany(java.util.List)>`__ - | :ref:`Usage Example ` - | :ref:`Fundamentals ` - - - .. code-block:: java - :copyable: true - - coll.insertMany( - Arrays.asList( - new Document("title", "Dangal").append("rating", "Not Rated"), - new Document("title", "The Boss Baby").append("rating", "PG"))); - - * - | **Update a Document** - | - | `API Documentation <{+api+}/apidocs/mongodb-driver-sync/com/mongodb/client/MongoCollection.html#updateOne(org.bson.conversions.Bson,org.bson.conversions.Bson)>`__ - | :ref:`Usage Example ` - | :ref:`Fundamentals ` - - - .. io-code-block:: - :copyable: true - - .. input:: - :language: java - - coll.updateOne( - Filters.eq("title", "Amadeus"), - Updates.set("imdb.rating", 9.5)); - - .. output:: - :language: json - :visible: false - - { title: 'Amadeus', imdb: { rating: 9.5, ... } } - - * - | **Update Multiple Documents** - | - | `API Documentation <{+api+}/apidocs/mongodb-driver-sync/com/mongodb/client/MongoCollection.html#updateMany(org.bson.conversions.Bson,org.bson.conversions.Bson)>`__ - | :ref:`Usage Example ` - | :ref:`Fundamentals ` - - - .. io-code-block:: - :copyable: true - - .. input:: - :language: java - - coll.updateMany( - Filters.eq("year", 2001), - Updates.inc("imdb.votes", 100)); - - .. output:: - :language: json - :visible: false - - [ - { title: 'A Beautiful Mind', year: 2001, imdb: { votes: 826257, ... }, - { title: 'Shaolin Soccer', year: 2001, imdb: { votes: 65442, ... }, - ... - ] - - * - | **Update an Array in a Document** - | - | `API Documentation <{+api+}/apidocs/mongodb-driver-sync/com/mongodb/client/MongoCollection.html#updateOne(org.bson.conversions.Bson,org.bson.conversions.Bson)>`__ - | :ref:`Fundamentals ` - - - .. io-code-block:: - :copyable: true - - .. input:: - :language: java - - coll.updateOne( - Filters.eq("title", "Cosmos"), - Updates.push("genres", "Educational")); - - .. output:: - :language: json - :visible: false - - { title: 'Cosmos', genres: [ 'Documentary', 'Educational' ], ...} - - * - | **Replace a Document** - | - | `API Documentation <{+api+}/apidocs/mongodb-driver-sync/com/mongodb/client/MongoCollection.html#replaceOne(org.bson.conversions.Bson,TDocument)>`__ - | :ref:`Usage Example ` - | :ref:`Fundamentals ` - - - .. io-code-block:: - :copyable: true - - .. input:: - :language: java - - coll.replaceOne( - Filters.and(Filters.eq("name", "Deli Llama"), Filters.eq("address", "2 Nassau St")), - new Document("name", "Lord of the Wings").append("zipcode", 10001)); - - .. output:: - :language: json - :visible: false - - { name: 'Lord of the Wings', zipcode: 10001 } - - * - | **Delete a Document** - | - | `API Documentation <{+api+}/apidocs/mongodb-driver-sync/com/mongodb/client/MongoCollection.html#deleteOne(org.bson.conversions.Bson)>`__ - | :ref:`Usage Example ` - | :ref:`Fundamentals ` - - - .. code-block:: java - :copyable: true - - coll.deleteOne(Filters.eq("title", "Congo")); - - * - | **Delete Multiple Documents** - | - | `API Documentation <{+api+}/apidocs/mongodb-driver-sync/com/mongodb/client/MongoCollection.html#deleteMany(org.bson.conversions.Bson)>`__ - | :ref:`Usage Example ` - | :ref:`Fundamentals ` - - - .. code-block:: java - :copyable: true - - coll.deleteMany(Filters.regex("title", "^Shark.*")); - - * - | **Bulk Write** - | - | `API Documentation <{+api+}/apidocs/mongodb-driver-sync/com/mongodb/client/MongoCollection.html#bulkWrite(java.util.List)>`__ - | :ref:`Usage Example ` - | :ref:`Fundamentals ` - - - .. code-block:: java - :copyable: true - - coll.bulkWrite( - Arrays.asList( - new InsertOneModel( - new Document().append("title", "A New Movie").append("year", 2022)), - new DeleteManyModel( - Filters.lt("year", 1970)))); - - * - | **Watch for Changes** - | - | `API Documentation <{+api+}/apidocs/mongodb-driver-sync/com/mongodb/client/MongoCollection.html#watch(java.util.List)>`__ - | :ref:`Usage Example ` - | :ref:`Fundamentals ` - - - .. code-block:: java - :copyable: true - - coll.watch(Arrays.asList( - Aggregates.match(Filters.gte("year", 2022)))); - - * - | **Access Data from a Cursor Iteratively** - | - | `API Documentation <{+api+}/apidocs/mongodb-driver-sync/com/mongodb/client/MongoCursor.html>`__ - | :ref:`Fundamentals ` - - - .. io-code-block:: - :copyable: true - - .. input:: - :language: java - - MongoCursor cursor = coll.find().cursor(); - while (cursor.hasNext()) { - System.out.println(cursor.next().toJson()); - } - - .. output:: - :language: json - :visible: false - - [ - { title: '2001: A Space Odyssey', ... }, - { title: 'The Sound of Music', ... }, - ... - ] - - * - | **Access Results from a Query as an Array** - | - | `API Documentation <{+api+}/apidocs/mongodb-driver-sync/com/mongodb/client/MongoIterable.html#into(A)>`__ - - - .. io-code-block:: - :copyable: true - - .. input:: - :language: java - - List resultList = new ArrayList(); - coll.find().into(resultList); - - .. output:: - :language: json - :visible: false - - [ - { title: '2001: A Space Odyssey', ... }, - { title: 'The Sound of Music', ... }, - ... - ] - - * - | **Count Documents** - | - | `API Documentation <{+api+}/apidocs/mongodb-driver-sync/com/mongodb/client/MongoCollection.html#countDocuments(org.bson.conversions.Bson)>`__ - | :ref:`Usage Example ` - - - .. io-code-block:: - :copyable: true - - .. input:: - :language: java - - coll.countDocuments(Filters.eq("year", 2000)); - - .. output:: - :language: none - :visible: false - - 618 - - * - | **List the Distinct Documents or Field Values** - | `API Documentation <{+api+}/apidocs/mongodb-driver-sync/com/mongodb/client/MongoCollection.html#distinct(java.lang.String,java.lang.Class)>`__ - | :ref:`Usage Example ` - - - .. io-code-block:: - :copyable: true - - .. input:: - :language: java - - coll.distinct("year", Integer.class); - - .. output:: - :language: none - :visible: false - - [ 1891, 1893, 1894, 1896, 1903, ... ] - - * - | **Limit the Number of Documents Retrieved** - | - | `API Documentation <{+api+}/apidocs/mongodb-driver-sync/com/mongodb/client/FindIterable.html#limit(int)>`__ - | :ref:`Fundamentals ` - - - .. io-code-block:: - :copyable: true - - .. input:: - :language: java - - coll.find().limit(2); - - .. output:: - :language: json - :visible: false - - [ - { title: 'My Neighbor Totoro', ... }, - { title: 'Amélie', ... } - ] - - * - | **Skip Retrieved Documents** - | - | `API Documentation <{+api+}/apidocs/mongodb-driver-sync/com/mongodb/client/FindIterable.html#skip(int)>`__ - | :ref:`Fundamentals ` - - - .. io-code-block:: - :copyable: true - - .. input:: - :language: java - - coll.find(Filters.regex("title", "^Rocky")).skip(2); - - .. output:: - :language: json - :visible: false - - [ - { title: 'Rocky III', ... }, - { title: 'Rocky IV', ... }, - { title: 'Rocky V', ... } - ] - - * - | **Sort the Documents When Retrieving Them** - | - | `API Documentation <{+api+}/apidocs/mongodb-driver-sync/com/mongodb/client/FindIterable.html#sort(org.bson.conversions.Bson)>`__ - | :ref:`Fundamentals ` - - - .. io-code-block:: - :copyable: true - - .. input:: - :language: java - - coll.find().sort(Sorts.ascending("year")); - - .. output:: - :language: json - :visible: false - - [ - { title: 'Newark Athlete', year: 1891, ... }, - { title: 'Blacksmith Scene', year: 1893, ...}, - { title: 'Dickson Experimental Sound Film', year: 1894}, - ... - ] - - * - | **Project Document Fields When Retrieving Them** - | - | `API Documentation <{+api+}/apidocs/mongodb-driver-sync/com/mongodb/client/FindIterable.html#projection(org.bson.conversions.Bson)>`__ - | :ref:`Usage Example ` - | :ref:`Fundamentals ` - - - .. io-code-block:: - :copyable: true - - .. input:: - :language: java - - coll.find().projection(Projections.fields( - Projections.excludeId(), - Projections.include("year", "imdb"))); - - .. output:: - :language: json - :visible: false - - [ - { year: 2012, imdb: { rating: 5.8, votes: 230, id: 8256 }}, - { year: 1985, imdb: { rating: 7.0, votes: 447, id: 1654 }}, - ... - ] - - * - | **Create an Index** - | - | `API Documentation <{+api+}/apidocs/mongodb-driver-sync/com/mongodb/client/MongoCollection.html#createIndex(org.bson.conversions.Bson)>`__ - | :ref:`Fundamentals ` - - - .. code-block:: java - :copyable: true - - coll.createIndex( - Indexes.compoundIndex( - Indexes.ascending("title"), - Indexes.descending("year"))); - - * - | **Search Text** - | - | `API Documentation <{+api+}/apidocs/mongodb-driver-sync/com/mongodb/client/MongoCollection.html#find()>`__ - | :ref:`Fundamentals ` - - - .. io-code-block:: - :copyable: true - - .. input:: - :language: java - - // only searches fields with text indexes - coll.find(Filters.text("zissou")); - - .. output:: - :language: json - :visible: false - - [ - { title: 'The Life Aquatic with Steve Zissou', ... } - ] - - * - | **Install the Driver Dependency with Maven** - - - .. code-block:: xml - :caption: pom.xml - :copyable: true - - - - org.mongodb - mongodb-driver-sync - {+full-version+} - - - - * - | **Install the Driver Dependency with Gradle** - - - .. code-block:: groovy - :caption: build.gradle - :copyable: true - - dependencies { - implementation 'org.mongodb:mongodb-driver-sync:{+full-version+}' - } - diff --git a/source/includes/figures/atlas_connection_connect_cluster.png b/source/includes/figures/atlas_connection_connect_cluster.png new file mode 100644 index 000000000..eba1fbc15 Binary files /dev/null and b/source/includes/figures/atlas_connection_connect_cluster.png differ diff --git a/source/includes/figures/atlas_connection_copy_string_java.png b/source/includes/figures/atlas_connection_copy_string_java.png deleted file mode 100644 index bda09f519..000000000 Binary files a/source/includes/figures/atlas_connection_copy_string_java.png and /dev/null differ diff --git a/source/includes/figures/atlas_connection_copy_uri_java.png b/source/includes/figures/atlas_connection_copy_uri_java.png new file mode 100644 index 000000000..bdd8ceaf4 Binary files /dev/null and b/source/includes/figures/atlas_connection_copy_uri_java.png differ diff --git a/source/includes/figures/atlas_connection_select_cluster.png b/source/includes/figures/atlas_connection_select_cluster.png deleted file mode 100644 index 2a8bb3f74..000000000 Binary files a/source/includes/figures/atlas_connection_select_cluster.png and /dev/null differ diff --git a/source/includes/quick-start/code-snippets/Movie.java b/source/includes/get-started/code-snippets/Movie.java similarity index 100% rename from source/includes/quick-start/code-snippets/Movie.java rename to source/includes/get-started/code-snippets/Movie.java diff --git a/source/includes/quick-start/code-snippets/QuickStart.java b/source/includes/get-started/code-snippets/QuickStart.java similarity index 100% rename from source/includes/quick-start/code-snippets/QuickStart.java rename to source/includes/get-started/code-snippets/QuickStart.java diff --git a/source/includes/quick-start/code-snippets/QuickStartPojoExample.java b/source/includes/get-started/code-snippets/QuickStartPojoExample.java similarity index 100% rename from source/includes/quick-start/code-snippets/QuickStartPojoExample.java rename to source/includes/get-started/code-snippets/QuickStartPojoExample.java diff --git a/source/includes/get-started/jdk-tls-issue.rst b/source/includes/get-started/jdk-tls-issue.rst new file mode 100644 index 000000000..c7f8ff5ea --- /dev/null +++ b/source/includes/get-started/jdk-tls-issue.rst @@ -0,0 +1,17 @@ +.. important:: TLS v1.3 Connection Error + + If your application generates an error that resembles the following + code, you might need to update your JDK to the latest patch release: + + .. code-block:: none + :copyable: false + + javax.net.ssl.SSLHandshakeException: extension (5) should not be presented in certificate_request + + This exception is a known issue when using the TLS 1.3 protocol with + some JDK versions. To resolve the error, update your JDK to one of + the following versions, or a newer version: + + - JDK 11.0.7 + - JDK 13.0.3 + - JDK 14.0.2 \ No newline at end of file diff --git a/source/includes/get-started/query-output.rst b/source/includes/get-started/query-output.rst new file mode 100644 index 000000000..f3954c7df --- /dev/null +++ b/source/includes/get-started/query-output.rst @@ -0,0 +1,14 @@ +.. code-block:: json + :copyable: false + + { + _id: ..., + plot: 'A young man is accidentally sent 30 years into the past...', + genres: [ 'Adventure', 'Comedy', 'Sci-Fi' ], + ... + title: 'Back to the Future', + ... + } + +If you encounter an error or see no output, ensure that you specified the +correct connection string and that you loaded the sample data. diff --git a/source/includes/get-started/quickstart-troubleshoot.rst b/source/includes/get-started/quickstart-troubleshoot.rst new file mode 100644 index 000000000..390289f41 --- /dev/null +++ b/source/includes/get-started/quickstart-troubleshoot.rst @@ -0,0 +1,6 @@ +.. note:: + + If you run into issues on this step, ask for help in the + :community-forum:`MongoDB Community Forums ` + or submit feedback by using the :guilabel:`Rate this page` + tab on the right or bottom right side of this page. \ No newline at end of file diff --git a/source/includes/quick-start/atlas-setup.rst b/source/includes/quick-start/atlas-setup.rst deleted file mode 100644 index e303743df..000000000 --- a/source/includes/quick-start/atlas-setup.rst +++ /dev/null @@ -1,48 +0,0 @@ -Set up a Free Tier Cluster in Atlas -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -After setting up your Java project dependencies, create a MongoDB cluster -where you can store and manage your data. Complete the -:atlas:`Get Started with Atlas ` guide -to set up a new Atlas account, create and launch a free tier MongoDB cluster, -load datasets, and interact with the data. - -After completing the steps in the Atlas guide, you should have a new MongoDB -cluster deployed in Atlas, a new database user, and sample datasets loaded -into your cluster. - -Connect to your Cluster ------------------------ - -In this step, we create and run an application that uses the MongoDB Java -driver to connect to your MongoDB cluster and run a query on the sample -data. - -We pass instructions to the driver on how to connect to your -MongoDB cluster in a string called the *connection string*. This string -includes information on the hostname or IP address and port of your -cluster, authentication mechanism, user credentials when applicable, and -other connection options. - -If you are connecting to an instance or cluster that is not hosted by Atlas, -see :ref:`Other Ways to Connect to MongoDB ` for -instructions on how to format your connection string. - -To retrieve your connection string for the cluster and user you created in -the previous step, log into your Atlas account and navigate to the -:guilabel:`Database` section and click :guilabel:`Connect` for the cluster that you -want to connect to as shown below. - -.. figure:: /includes/figures/atlas_connection_select_cluster.png - :alt: Atlas Connection GUI cluster selection screen - -Proceed to the :guilabel:`Connect Your Application` step and select the Java driver. -Select "4.3 or Later" for the version. -Click the :guilabel:`Copy` icon to copy the *connection string* to your clipboard as -shown below. - -.. figure:: /includes/figures/atlas_connection_copy_string_java.png - :alt: Atlas Connection GUI connection string screen - -Save your Atlas connection string in a safe location that you can access -for the next step. diff --git a/source/includes/quick-start/create-project.rst b/source/includes/quick-start/create-project.rst deleted file mode 100644 index bf40a1876..000000000 --- a/source/includes/quick-start/create-project.rst +++ /dev/null @@ -1,10 +0,0 @@ -This guide shows you how to add the MongoDB Java driver dependencies using -Maven or Gradle. We recommend that you use an integrated development -environment (IDE) such as Intellij IDEA or Eclipse IDE make it more convenient -to configure Maven or Gradle to build and run your project. - -If you are not using an IDE, see -`Building Maven `_ -or -`Creating New Gradle Builds `_ -For more information about how to set up your project. diff --git a/source/includes/quick-start/gradle-versioned.rst b/source/includes/quick-start/gradle-versioned.rst deleted file mode 100644 index ccd5f1191..000000000 --- a/source/includes/quick-start/gradle-versioned.rst +++ /dev/null @@ -1,6 +0,0 @@ -.. code-block:: groovy - - dependencies { - implementation 'org.mongodb:mongodb-driver-sync:{+full-version+}' - } - diff --git a/source/includes/quick-start/install-jdk.rst b/source/includes/quick-start/install-jdk.rst deleted file mode 100644 index 56dc8fd46..000000000 --- a/source/includes/quick-start/install-jdk.rst +++ /dev/null @@ -1,3 +0,0 @@ -Make sure that your system has JDK 8 or later installed. For more information -on how to check your version of Java and install the JDK, see the -`Oracle Overview of JDK Installation documentation `_. \ No newline at end of file diff --git a/source/includes/quick-start/jdk-tls-issue.rst b/source/includes/quick-start/jdk-tls-issue.rst deleted file mode 100644 index dd35ae2a9..000000000 --- a/source/includes/quick-start/jdk-tls-issue.rst +++ /dev/null @@ -1,20 +0,0 @@ -.. important:: Known connection issue when using TLS v1.3 - - If you encounter an error connecting to your MongoDB instance or cluster - that resembles the following while running your application, you might need - to update your JDK to the latest patch release: - - .. code-block:: none - :copyable: false - - javax.net.ssl.SSLHandshakeException: extension (5) should not be presented in certificate_request - - This exception is a known issue when using the TLS 1.3 protocol with - specific versions of JDK, but was fixed for the following releases: - - - JDK 11.0.7 - - JDK 13.0.3 - - JDK 14.0.2 - - To resolve this error, update your JDK to one of the preceding patch - versions or a newer one. diff --git a/source/includes/quick-start/maven-versioned.rst b/source/includes/quick-start/maven-versioned.rst deleted file mode 100644 index e0bc84e78..000000000 --- a/source/includes/quick-start/maven-versioned.rst +++ /dev/null @@ -1,10 +0,0 @@ -.. code-block:: xml - - - - org.mongodb - mongodb-driver-sync - {+full-version+} - - - diff --git a/source/includes/quick-start/next-steps.rst b/source/includes/quick-start/next-steps.rst deleted file mode 100644 index 572be2465..000000000 --- a/source/includes/quick-start/next-steps.rst +++ /dev/null @@ -1,3 +0,0 @@ -Learn how to read and modify data using the Java driver in our Fundamentals -CRUD guide or how to perform common operations from our -:doc:`Usage Examples `. diff --git a/source/includes/quick-start/overview.rst b/source/includes/quick-start/overview.rst deleted file mode 100644 index af7db12be..000000000 --- a/source/includes/quick-start/overview.rst +++ /dev/null @@ -1,14 +0,0 @@ -This guide shows you how to create an application that uses the **Java driver** -to connect to a **MongoDB Atlas cluster**. If you prefer to connect to MongoDB -using a different driver or programming language, see our -:driver:`list of official MongoDB drivers <>`. - -The Java driver lets you connect to and communicate with MongoDB clusters -from a Java application. - -MongoDB Atlas is a fully-managed cloud database service that hosts your data -on MongoDB clusters. In this guide, we show you how to get started with your -own free (no credit card required) cluster. - -Consult the following steps to connect your Java application with a MongoDB Atlas -cluster. diff --git a/source/includes/quick-start/pojo-query-output.rst b/source/includes/quick-start/pojo-query-output.rst deleted file mode 100644 index 1c09599ea..000000000 --- a/source/includes/quick-start/pojo-query-output.rst +++ /dev/null @@ -1,15 +0,0 @@ -When you run the ``QuickStartPojoExample`` class, it should output the details of the -movie from the sample dataset, which resemble the following: - -.. code-block:: none - :copyable: false - - Movie [ - plot=A young man is accidentally sent 30 years into the past..., - genres=[Adventure, Comedy, Sci-Fi], - title=Back to the Future - ] - -If you receive no output or an error, check whether you included the proper -connection string in your Java class, and whether you loaded the sample dataset -into your MongoDB Atlas cluster. diff --git a/source/includes/quick-start/query-output.rst b/source/includes/quick-start/query-output.rst deleted file mode 100644 index ab2b9d210..000000000 --- a/source/includes/quick-start/query-output.rst +++ /dev/null @@ -1,18 +0,0 @@ -When you run the ``QuickStart`` class, it should output the details of the -movie from the sample dataset, which will resemble the following: - -.. code-block:: json - :copyable: false - - { - _id: ..., - plot: 'A young man is accidentally sent 30 years into the past...', - genres: [ 'Adventure', 'Comedy', 'Sci-Fi' ], - ... - title: 'Back to the Future', - ... - } - -If you receive no output or an error, check whether you included the proper -connection string in your Java class, and whether you loaded the sample dataset -into your MongoDB Atlas cluster. diff --git a/source/index.txt b/source/index.txt index 4b6a19399..b382ca05b 100644 --- a/source/index.txt +++ b/source/index.txt @@ -18,7 +18,7 @@ MongoDB Java Driver :titlesonly: :maxdepth: 1 - Getting Started + Get Started Connect CRUD Operations Data Formats @@ -37,7 +37,7 @@ Introduction Welcome to the documentation site for the Java Driver, the official MongoDB driver for synchronous Java applications. -Follow the :ref:`Quick Start ` guide to learn how +Follow the :ref:`Get Started ` tutorial to learn how to add the driver to your project by using `Maven `__ or `Gradle `__ and how to set up a runnable app. @@ -53,11 +53,11 @@ deployments running on one of the following hosted services or editions: .. include:: /includes/fact-environments.rst -Quick Start +Get Started ----------- Learn how to establish a connection to MongoDB Atlas and begin -working with data in the :doc:`Quick Start ` section. +working with data in the :ref:`Get Started ` section. Quick Reference --------------- @@ -127,12 +127,6 @@ Learn how to report bugs, contribute to the driver, and find additional resources for asking questions and receiving help in the :doc:`Issues & Help ` section. -Driver Integrations -------------------- - -Learn more about tools and frameworks that you can use together -with {+driver-short+} in the :ref:`java-integrations` section. - Compatibility ------------- diff --git a/source/usage-examples.txt b/source/usage-examples.txt index d314e846b..489e71b86 100644 --- a/source/usage-examples.txt +++ b/source/usage-examples.txt @@ -50,7 +50,7 @@ or you can Once you have imported the dataset, you can copy and paste a usage example into your development environment of choice. You can follow the -:doc:`quick start guide ` to learn more about getting +:ref:`Get Started ` tutorial to learn more about getting started with the MongoDB Java driver. Once you've copied a usage example, you must edit the connection URI to get the example connected to your MongoDB instance: