Skip to content

Commit 17f01d8

Browse files
norareidynorareidy
authored
DOCSP-47777: Rework get started (#619)
* DOCSP-47777: Rework get started * edits * snooty * fixes * build errors * RM feedback * fix * capitalize * punctuation * toc * add back integrations * tech review
1 parent 886a04c commit 17f01d8

33 files changed

+311
-771
lines changed

‎snooty.toml

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -7,7 +7,7 @@ intersphinx = [
77
]
88

99
toc_landing_pages = [
10-
"/getting-started",
10+
"/get-started",
1111
"/connection",
1212
"/crud",
1313
"/crud/builders",

‎source/get-started.txt

Lines changed: 52 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,52 @@
1+
.. _java-get-started:
2+
3+
================================
4+
Get Started with the Java Driver
5+
================================
6+
7+
.. facet::
8+
:name: genre
9+
:values: tutorial
10+
11+
.. meta::
12+
:description: Learn how to create an app to connect to MongoDB deployment by using the {+driver-short+}.
13+
:keywords: quick start, tutorial, basics
14+
15+
.. toctree::
16+
17+
Download & Install </get-started/download-and-install/>
18+
Create a Deployment </get-started/create-deployment/>
19+
Create a Connection String </get-started/connection-string/>
20+
Connect to MongoDB </get-started/connect-to-mongodb/>
21+
Next Steps </get-started/next-steps/>
22+
Databases & Collections </get-started/databases-collections/>
23+
Integrations </get-started/integrations/>
24+
25+
Overview
26+
--------
27+
28+
The {+driver-short+} is a synchronous API that you can use to interact with MongoDB
29+
from your Java application. This guide shows you how to create an application that
30+
uses the {+driver-short+} to connect to a MongoDB cluster hosted on MongoDB Atlas
31+
and query data in your cluster.
32+
33+
.. tip::
34+
35+
:atlas:`MongoDB Atlas </getting-started/>` is a fully managed cloud database service
36+
that hosts your MongoDB deployments. You can create your own free (no credit card required)
37+
MongoDB Atlas deployment by following the steps in this guide.
38+
39+
Follow this tutorial to connect a sample Java application to a MongoDB Atlas
40+
deployment. The tutorial includes the following sections:
41+
42+
- :ref:`java-get-started-download-and-install`: Learn how to install
43+
the {+driver-short+}.
44+
- :ref:`java-get-started-create-deployment`: Learn how to create
45+
a free MongoDB deployment on Atlas.
46+
- :ref:`java-get-started-connection-string`: Learn how to retrieve
47+
your Atlas deployment's connection string.
48+
- :ref:`java-connect-to-mongodb`: Learn how to create an application
49+
that connects to MongoDB and queries data stored in your deployment.
50+
51+
If you prefer to connect to MongoDB using a different driver or
52+
programming language, see our :driver:`list of official drivers <>`.

‎source/get-started/connect-to-mongodb.txt

Lines changed: 52 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,52 @@
1+
.. _java-connect-to-mongodb:
2+
3+
==================
4+
Connect to MongoDB
5+
==================
6+
7+
.. facet::
8+
:name: genre
9+
:values: tutorial
10+
11+
.. meta::
12+
:keywords: test connection, runnable, code example
13+
14+
After retrieving the connection string for your MongoDB Atlas deployment,
15+
you can connect to the deployment from your Java application and query
16+
the Atlas sample datasets.
17+
18+
.. procedure::
19+
:style: connected
20+
21+
.. step:: Create your Java application file
22+
23+
In your project's base package directory, create a file called
24+
``QuickStart.java``. Copy and paste the following code into this file,
25+
which queries the ``movies`` collection in the ``sample_mflix`` database:
26+
27+
.. literalinclude:: /includes/get-started/code-snippets/QuickStart.java
28+
:start-after: begin QuickStart
29+
:end-before: end QuickStart
30+
:language: java
31+
:dedent:
32+
33+
.. step:: Assign the connection string
34+
35+
Replace the ``<connection string uri>`` placeholder with the connection string
36+
that you copied from the :ref:`java-get-started-connection-string` step of this
37+
guide.
38+
39+
.. step:: Run your Java application
40+
41+
Run your application in your IDE or your shell. Your output
42+
contains details about the retrieved movie document:
43+
44+
.. include:: /includes/get-started/query-output.rst
45+
46+
.. include:: /includes/get-started/jdk-tls-issue.rst
47+
48+
After you complete these steps, you have a Java application that
49+
connects to your MongoDB deployment, runs a query on the sample
50+
data, and returns a matching document.
51+
52+
.. include:: /includes/get-started/quickstart-troubleshoot.rst

‎source/get-started/connection-string.txt

Lines changed: 53 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,53 @@
1+
.. _java-get-started-connection-string:
2+
3+
==========================
4+
Create a Connection String
5+
==========================
6+
7+
You can connect to your MongoDB deployment by providing a
8+
**connection URI**, also called a *connection string*, which
9+
instructs the driver on how to connect to a MongoDB deployment
10+
and how to behave while connected.
11+
12+
The connection string includes the hostname or IP address and
13+
port of your deployment, the authentication mechanism, user credentials
14+
when applicable, and connection options.
15+
16+
.. procedure::
17+
:style: connected
18+
19+
.. step:: Find your MongoDB Atlas connection string
20+
21+
To retrieve your connection string for the deployment that
22+
you created in the :ref:`previous step <java-get-started-create-deployment>`,
23+
log into your Atlas account and navigate to the
24+
:guilabel:`Clusters` section. Click the :guilabel:`Connect` button
25+
for your new deployment, as shown in the following screenshot:
26+
27+
.. figure:: /includes/figures/atlas_connection_connect_cluster.png
28+
:alt: The connect button in the clusters section of the Atlas UI
29+
30+
Then, proceed to the :guilabel:`Connect your application` section. Select
31+
"Java" from the :guilabel:`Driver` selection menu and the version
32+
that best matches the version you installed from the :guilabel:`Version`
33+
selection menu.
34+
35+
.. step:: Copy your connection string
36+
37+
Click the button on the right of the connection string to copy it to
38+
your clipboard, as shown in the following screenshot:
39+
40+
.. figure:: /includes/figures/atlas_connection_copy_uri_java.png
41+
:alt: The connection string copy button in the Atlas UI
42+
43+
.. step:: Edit your connection string placeholders
44+
45+
Paste your connection string into a file in your preferred text editor
46+
and save this file to a safe location for later use. In your connection
47+
string, replace the ``<db_username>`` and ``<db_password>`` placeholders with
48+
your database user's username and password.
49+
50+
After completing these steps, you have a connection string that
51+
contains your database username and password.
52+
53+
.. include:: /includes/get-started/quickstart-troubleshoot.rst

‎source/get-started/create-deployment.txt

Lines changed: 29 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,29 @@
1+
.. _java-get-started-create-deployment:
2+
3+
===========================
4+
Create a MongoDB Deployment
5+
===========================
6+
7+
You can create a free tier MongoDB deployment on MongoDB Atlas
8+
to store and manage your data. MongoDB Atlas hosts and manages
9+
your MongoDB database in the cloud.
10+
11+
.. procedure::
12+
:style: connected
13+
14+
.. step:: Create a free MongoDB deployment on Atlas
15+
16+
Complete the :atlas:`Get Started with Atlas </getting-started?tck=docs_driver_java>`
17+
guide to set up a new Atlas account and a free tier MongoDB deployment.
18+
Ensure that you :atlas:`load sample data </sample-data/>` and
19+
:atlas:`add your IP address </security/add-ip-address-to-list/>` to the IP access
20+
list.
21+
22+
.. step:: Save your credentials
23+
24+
After you create your database user, save that user's
25+
username and password to a safe location for use in an upcoming step.
26+
27+
After you complete these steps, you have a new free tier MongoDB
28+
deployment on Atlas, database user credentials, and sample data loaded
29+
in your database.

‎source/getting-started/databases-collections.txt renamed to ‎source/get-started/databases-collections.txt

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,5 @@
1+
.. _java-db-coll:
2+
13
=========================
24
Databases and Collections
35
=========================

‎source/get-started/download-and-install.txt

Lines changed: 61 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,61 @@
1+
.. _java-get-started-download-and-install:
2+
3+
====================
4+
Download and Install
5+
====================
6+
7+
Complete the following steps to install the {+driver-short+} and
8+
its dependencies in your development environment.
9+
10+
.. procedure::
11+
:style: connected
12+
13+
.. step:: Install the driver dependencies
14+
15+
Before you begin this tutorial, ensure that you install
16+
the following dependencies:
17+
18+
- `JDK <https://www.oracle.com/java/technologies/javase-downloads.html>`__
19+
version 8 or later
20+
- Integrated development environment (IDE), such as `IntelliJ IDEA <https://www.jetbrains.com/idea/download/>`__
21+
or `Eclipse <https://www.eclipse.org/downloads/packages/>`__
22+
23+
.. note::
24+
25+
This tutorial shows how to install the {+driver-short+} by using
26+
Maven or Gradle in an IDE. If you do not use an IDE, visit `Building Maven
27+
<https://maven.apache.org/guides/development/guide-building-maven.html>`__
28+
or `Creating New Gradle Builds <https://guides.gradle.org/creating-new-gradle-builds/>`__
29+
to learn how to set up your project.
30+
31+
.. step:: Install the {+driver-short+}
32+
33+
In your IDE, create a new `Maven <https://maven.apache.org/>`__ or `Gradle <https://gradle.org/>`__
34+
project. If you use Maven, add the following code to your ``pom.xml`` dependencies list:
35+
36+
.. code-block:: xml
37+
38+
<dependencies>
39+
<dependency>
40+
<groupId>org.mongodb</groupId>
41+
<artifactId>mongodb-driver-sync</artifactId>
42+
<version>{+full-version+}</version>
43+
</dependency>
44+
</dependencies>
45+
46+
If you use Gradle, add the following code to your ``build.gradle`` dependencies list:
47+
48+
.. code-block:: groovy
49+
50+
dependencies {
51+
implementation 'org.mongodb:mongodb-driver-sync:{+full-version+}'
52+
}
53+
54+
After you configure your dependencies, ensure they are available to your
55+
project by running your dependency manager and refreshing
56+
the project in your IDE.
57+
58+
After you complete these steps, you have a new project
59+
and the driver dependencies installed.
60+
61+
.. include:: /includes/get-started/quickstart-troubleshoot.rst

‎source/getting-started/integrations.txt renamed to ‎source/get-started/integrations.txt

File renamed without changes.

‎source/get-started/next-steps.txt

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
.. _java-get-started-next-steps:
2+
3+
==========
4+
Next Steps
5+
==========
6+
7+
Congratulations on completing the tutorial!
8+
9+
In this tutorial, you created a {+driver-short+} application that
10+
connects to a MongoDB deployment hosted on MongoDB Atlas
11+
and retrieves a document that matches a query.
12+
13+
You can continue to develop your sample application by
14+
visiting the following guides:
15+
16+
- :ref:`java-db-coll`: Learn more about interacting with
17+
MongoDB databases and collections.
18+
- :ref:`java-integrations`: Learn about the third-party
19+
integrations that you can use with the {+driver-short+}.

0 commit comments

Comments
 (0)