DOCSP-12160: quickstart pojos (#94)

* DOCSP-12160: quickstart pojos

Author: Chris Cho

source/includes/quick-start/code-snippets/Movie.java

@@ -0,0 +1,35 @@
+package fundamentals;
+
+import java.util.List;
+
+
+// begin moviePojo
+public class Movie {
+    String plot;
+    List<String> genres;
+    String title;
+
+    public String getPlot() {
+        return plot;
+    }
+    public void setPlot(String plot) {
+        this.plot = plot;
+    }
+    public List<String> getGenres() {
+        return genres;
+    }
+    public void setGenres(List<String> genres) {
+        this.genres = genres;
+    }
+    public String getTitle() {
+        return title;
+    }
+    public void setTitle(String title) {
+        this.title = title;
+    }
+    @Override
+    public String toString() {
+        return "Movie [\n  plot=" + plot + ",\n  genres=" + genres + ",\n  title=" + title + "\n]";
+    }
+}
+// end moviePojo

source/includes/quick-start/code-snippets/QuickStart.java

@@ -0,0 +1,26 @@
+package fundamentals;
+
+// begin QuickStart
+import static com.mongodb.client.model.Filters.eq;
+
+import org.bson.Document;
+
+import com.mongodb.client.MongoClient;
+import com.mongodb.client.MongoClients;
+import com.mongodb.client.MongoCollection;
+import com.mongodb.client.MongoDatabase;
+
+public static void main( String[] args ) {
+
+    // Replace the uri string with your MongoDB deployment's connection string
+    String uri = "mongodb+srv://<user>:<password>@<cluster-url>?retryWrites=true&w=majority";
+
+    try (MongoClient mongoClient = MongoClients.create(uri)) {
+        MongoDatabase database = mongoClient.getDatabase("sample_mflix");
+        MongoCollection<Document> collection = database.getCollection("movies");
+
+        Document doc = collection.find(eq("title", "Back to the Future")).first();
+        System.out.println(doc.toJson());
+    }
+}
+// end QuickStart

source/includes/quick-start/code-snippets/QuickStartPojoExample.java

@@ -0,0 +1,36 @@
+package fundamentals;
+
+// begin PojoQuickstart
+import static com.mongodb.MongoClientSettings.getDefaultCodecRegistry;
+import static com.mongodb.client.model.Filters.eq;
+import static org.bson.codecs.configuration.CodecRegistries.fromProviders;
+import static org.bson.codecs.configuration.CodecRegistries.fromRegistries;
+
+import org.bson.codecs.configuration.CodecProvider;
+import org.bson.codecs.configuration.CodecRegistry;
+import org.bson.codecs.pojo.PojoCodecProvider;
+
+import com.mongodb.client.MongoClient;
+import com.mongodb.client.MongoClients;
+import com.mongodb.client.MongoCollection;
+import com.mongodb.client.MongoDatabase;
+
+public class QuickStartPojoExample {
+
+    public static void main(String[] args) {
+        CodecProvider pojoCodecProvider = PojoCodecProvider.builder().automatic(true).build();
+        CodecRegistry pojoCodecRegistry = fromRegistries(getDefaultCodecRegistry(), fromProviders(pojoCodecProvider));
+
+        // Replace the uri string with your MongoDB deployment's connection string
+        String uri = "mongodb+srv://<user>:<password>@<cluster-url>?retryWrites=true&w=majority";
+
+        try (MongoClient mongoClient = MongoClients.create(uri)) {
+            MongoDatabase database = mongoClient.getDatabase("sample_mflix").withCodecRegistry(pojoCodecRegistry);
+            MongoCollection<Movie> collection = database.getCollection("movies", Movie.class);
+
+            Movie movie = collection.find(eq("title", "Back to the Future")).first();
+            System.out.println(movie);
+        }
+    }
+}
+// end PojoQuickstart

source/includes/quick-start/gradle-versioned.rst

@@ -1,6 +1,6 @@
 .. code-block:: groovy
 
    dependencies {
-     compile 'org.mongodb:mongodb-driver-sync:4.1.0'
+     compile 'org.mongodb:mongodb-driver-sync:4.3.0'
    }
 

source/includes/quick-start/maven-versioned.rst

@@ -4,7 +4,7 @@
        <dependency>
            <groupId>org.mongodb</groupId>
            <artifactId>mongodb-driver-sync</artifactId>
-           <version>4.1.0</version>
+           <version>4.3.0</version>
        </dependency>
    </dependencies>
 

source/includes/quick-start/pojo-query-output.rst

@@ -0,0 +1,14 @@
+When you run the ``QuickStartPojoExample`` class, it should output the details of the
+movie from the sample dataset which will look something like this:
+
+.. code-block:: none
+
+   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.

source/includes/quick-start/query-output.rst

@@ -1,4 +1,4 @@
-When you run the ``QuickStart`` class, it should output the details of the 
+When you run the ``QuickStart`` class, it should output the details of the
 movie from the sample dataset which will look something like this:
 
 .. code-block:: json
@@ -14,4 +14,4 @@ movie from the sample dataset which will look something like this:
 
 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
-in your MongoDB Atlas cluster
+into your MongoDB Atlas cluster.

source/quick-start.txt

@@ -40,14 +40,14 @@ If you are using `Gradle <https://gradle.org/>`__, add the following to your
 
 .. include:: /includes/quick-start/gradle-versioned.rst
 
-Once you configure your dependencies, make sure they are available to your
-project which involves running your dependency manager and/or refreshing
+Once you configure your dependencies, ensure they are available to your
+project which may require running your dependency manager and refreshing
 the project in your IDE.
 
 .. note::
-   You may need to configure the JDK version in your IDE and/or dependency
+   You may need to configure the JDK version in your IDE and dependency
    file. Refer to the documentation provided by maintainers of your IDE
-   and/or dependency management system.
+   and dependency management system.
 
    For example, if you build with Maven in the IntelliJ IDE, you need to
    specify your JDK version explicitly in the ``properties`` section in your
@@ -75,40 +75,59 @@ 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.
-Make sure to replace the "<password>" section of the connection string with
+Ensure you replace the "<password>" section of the connection string with
 the password you created for your user that has **atlasAdmin** permissions:
 
-.. code-block:: java
+.. literalinclude:: /includes/quick-start/code-snippets/QuickStart.java
+   :start-after: begin QuickStart
+   :end-before: end QuickStart
+   :language: java
+   :dedent:
 
-   import static com.mongodb.client.model.Filters.eq;
+.. include:: /includes/quick-start/query-output.rst
 
-   import org.bson.Document;
+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.
 
-   import com.mongodb.client.MongoClient;
-   import com.mongodb.client.MongoClients;
-   import com.mongodb.client.MongoCollection;
-   import com.mongodb.client.MongoDatabase;
+Working with POJOs (Optional)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-   public static void main( String[] args ) {
+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.
 
-       String uri = "mongodb+srv://<user>:<password>@<cluster-url>?retryWrites=true&w=majority";
-       MongoClient mongoClient = MongoClients.create(uri);
+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:
 
-       MongoDatabase database = mongoClient.getDatabase("sample_mflix");
-       MongoCollection<Document> collection = database.getCollection("movies");
+.. literalinclude:: /includes/quick-start/code-snippets/Movie.java
+   :start-after: begin moviePojo
+   :end-before: end moviePojo
+   :language: java
+   :dedent:
 
-       Document doc = collection.find(eq("title", "Back to the Future")).first();
-       System.out.println(doc.toJson());
+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 "<password>" section of the connection string with
+the password you created for your user that has **atlasAdmin** permissions:
 
-       mongoClient.close();
-   }
+.. literalinclude:: /includes/quick-start/code-snippets/QuickStartPojoExample.java
+   :start-after: begin PojoQuickstart
+   :end-before: end PojoQuickstart
+   :language: java
+   :dedent:
 
-.. include:: /includes/quick-start/query-output.rst
+.. include:: /includes/quick-start/pojo-query-output.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.
+See the following links for more information on using POJOs to store and
+retrieve data:
 
+- :doc:`Guide on using POJOs to store and retrieve data</fundamentals/data-formats/document-data-format-pojo>`
+- :doc:`Guide on custom serialization of POJOs </fundamentals/data-formats/pojo-customization>`
 
 Next steps
 ----------