Skip to content

Commit 385cce1

Browse files
norareidynorareidy
committed
DOCSP-47777: Rework get started
1 parent 52989b6 commit 385cce1

28 files changed

+269
-256
lines changed

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

File renamed without changes.

‎source/get-started.txt

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

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

Lines changed: 55 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,55 @@
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>`` 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+
If you encounter an error or see no output, ensure that you specified the
47+
correct connection string and that you loaded the sample data.
48+
49+
.. include:: /includes/get-started/jdk-tls-issue.rst
50+
51+
After you complete these steps, you have a Java application that
52+
connects to your MongoDB deployment, runs a query on the sample
53+
data, and returns a matching document.
54+
55+
.. 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_string_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: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,28 @@
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 **load sample data** and **add your IP address** to the IP access
19+
list.
20+
21+
.. step:: Save your credentials
22+
23+
After you create your database user, save that user's
24+
username and password to a safe location for use in an upcoming step.
25+
26+
After you complete these steps, you have a new free tier MongoDB
27+
deployment on Atlas, database user credentials, and sample data loaded
28+
in your database.

‎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/get-started/next-steps.txt

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
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+
Learn more about the {+driver-short+} from the following resources:
14+
15+
- Learn how to perform read operations in the :ref:`<java-read-operations>` guide.
16+
- Learn how to perform write operations in the :ref:`<java-write-operations>` guide.

0 commit comments

Comments
 (0)