Merge pull request #8 from rustagir/DOCSP-37780-tutorials-db-coll

DOCSP-37780: db collection tutorial

Author: rustagir

source/tutorials.txt

@@ -7,4 +7,5 @@ Tutorials
 .. toctree::
 
    /tutorials/connect/
+   /tutorials/db-coll/
 

source/tutorials/db-coll.txt

@@ -0,0 +1,276 @@
+.. _javars-db-coll:
+
+=========================
+Databases and Collections
+=========================
+
+.. contents:: On this page
+   :local:
+   :backlinks: none
+   :depth: 1
+   :class: singlecol
+
+MongoDB organizes data in a hierarchical structure. A MongoDB deployment
+contains one or more databases, and each database contains one or more
+collections. In each collection, MongoDB stores data as documents that
+contain field-and-value pairs.
+
+Prerequisites
+-------------
+
+You must include the following import statements in your program to run the
+code examples in this guide:
+
+.. code-block:: java
+
+   import com.mongodb.reactivestreams.client.MongoClients;
+   import com.mongodb.reactivestreams.client.MongoClient;
+   import com.mongodb.reactivestreams.client.MongoCollection;
+   import com.mongodb.reactivestreams.client.MongoDatabase;
+   import static com.mongodb.client.model.Filters.*;
+   import com.mongodb.client.model.CreateCollectionOptions;
+   import com.mongodb.client.model.ValidationOptions;
+
+.. important::
+
+   This guide uses the ``Subscriber`` implementations, which are
+   described in the :ref:`Quick Start Primer <javars-primer>`.
+
+Connect to a MongoDB Deployment
+-------------------------------
+
+First, connect to a running MongoDB deployment.
+
+The following code connects to a standalone MongoDB deployment running
+on ``localhost`` on port ``27017``:
+
+.. code-block:: java
+
+   MongoClient mongoClient = MongoClients.create();
+
+To learn more about connecting to MongoDB deployments,
+see the :ref:`javars-connect` tutorial.
+
+Access a Database
+-----------------
+
+Once you have a ``MongoClient`` instance connected to a MongoDB
+deployment, use the ```getDatabase()`` method to access a database.
+
+Pass the name of the database as a parameter to the ``getDatabase()``
+method. If a database does not exist, MongoDB creates it when
+you insert any data into the database.
+
+The following example accesses the ``test`` database:
+
+.. code-block:: java
+
+   MongoDatabase database = mongoClient.getDatabase("test");
+
+.. note::
+
+   ``MongoDatabase`` instances are immutable. To learn more, see the
+   :ref:`Immutability <javars-immutability>` section of this guide.
+
+Access a Collection
+-------------------
+
+After you create a ``MongoDatabase`` instance, use the
+``getCollection()`` method to access a collection from within that
+database.
+
+Pass the name of the collection as a parameter to the ``getCollection()``
+method.
+
+Using the ``database`` instance created in the preceding section, the
+following code accesses the collection named ``myTestCollection``:
+
+.. code-block:: java
+
+   MongoCollection<Document> coll = database.getCollection("myTestCollection");
+
+.. note::
+   
+   ``MongoCollection`` instances are immutable. To learn more, see the
+   :ref:`Immutability <javars-immutability>` section of this guide.
+
+If a collection with that name does not exist, MongoDB creates it when
+you first insert data into that collection.
+
+You can also directly create a collection with various options, such
+as setting the maximum size or creating documentation validation rules.
+
+Create a Collection
+-------------------
+
+The driver provides the ``createCollection()`` method to
+directly create a collection. When you create a
+collection, you can specify various collection options, such as a
+maximum size or documentation validation rules, with the
+``CreateCollectionOptions`` class.
+
+If you are not specifying any options, you do not need to directly
+create the collection since MongoDB automatically creates new
+collections when you first insert data.
+
+Capped Collection
+~~~~~~~~~~~~~~~~~
+
+The following operation creates a capped collection limited to 1
+megabyte:
+
+.. code-block:: java
+
+   database.createCollection(
+       "cappedCollection",
+       new CreateCollectionOptions().capped(true).sizeInBytes(0x100000)
+   ).subscribe(new OperationSubscriber<Void>());
+
+To learn more about capped collections, see :manual:`Capped Collections
+</core/capped-collections/>` in the Server manual.
+
+Document Validation
+~~~~~~~~~~~~~~~~~~~
+
+MongoDB allows you to validate documents during
+updates and inserts. Validation rules are specified on a collection
+level by using the ``ValidationOptions`` class, which takes a
+filter document that specifies the validation rules or expressions.
+
+The following example creates a collection with schema validation:
+
+.. code-block:: java
+
+   ValidationOptions collOptions = new ValidationOptions().validator(
+            Filters.or(Filters.exists("email"), Filters.exists("phone")));
+    
+   database.createCollection(
+       "contacts", 
+       new CreateCollectionOptions().validationOptions(collOptions)
+   ).subscribe(new OperationSubscriber<Void>());
+
+To learn more about document validation, see :manual:`Schema Validation
+</core/schema-validation/>` in the Server manual.
+
+Get A List of Collections
+-------------------------
+
+You can get a list of the collections in a database by using the
+``MongoDatabase.listCollectionNames()`` method:
+
+.. code-block:: java
+
+   database.listCollectionNames().subscribe(new PrintToStringSubscriber<String>());
+
+Drop a Collection
+-----------------
+
+You can drop a collection and delete all of the data in the collection
+by using the ``MongoCollection.drop()`` method:
+
+.. code-block:: java
+
+   MongoCollection<Document> collection = database.getCollection("contacts");
+   collection.drop().subscribe(new OperationSubscriber<Void>());
+
+.. _javars-immutability:
+
+Immutability
+------------
+
+``MongoDatabase`` and ``MongoCollection`` instances are immutable. To
+create new instances from existing instances that have different
+properties, such as different :manual:`read concerns
+</reference/read-concern/>`, :manual:`read preferences
+</reference/read-preference/>`, and :manual:`write concerns
+</reference/write-concern/>`, the ``MongoDatabase`` and
+``MongoCollection`` class provides the following methods:
+
+- ``MongoDatabase.withReadConcern()``
+- ``MongoDatabase.withReadPreference()``
+- ``MongoDatabase.withWriteConcern()``
+- ``MongoCollection.withReadConcern()``
+- ``MongoCollection.withReadPreference()``
+- ``MongoCollection.withWriteConcern()``
+
+.. TODO To learn more, see the `Read Operations` and `Write Operations` tutorials.
+
+CodecRegistry
+-------------
+
+An overload of the ``getCollection()`` method allows you to specify a
+different class for representing BSON documents. For example, you
+might want to use the strict and type-safe ``BsonDocument`` class to
+model your documents when performing CRUD operations:
+
+.. code-block:: java
+
+   // pass BsonDocument.class as the second argument
+   MongoCollection<BsonDocument> collection = database
+       .getCollection("mycoll", BsonDocument.class);
+    
+   // insert a document
+   BsonDocument document = BsonDocument.parse("{x: 1}");
+   collection.insertOne(document).subscribe(new OperationSubscriber<Void>());
+   document.append("x", new BsonInt32(2)).append("y", new BsonInt32(3));
+    
+   // replace a document
+   collection.replaceOne(Filters.eq("_id", document.get("_id")), document)
+       .subscribe(new PrintSubscriber<UpdateResult>("Update Result: %s"));
+    
+   // find documents
+   collection.find().subscribe(new PrintDocumentSubscriber());
+
+There are two requirements that any class must meet to be used in
+this way:
+
+- ``Codec`` instance for the class must be registered in the
+  ``CodecRegistry`` for the ``MongoCollection``.
+
+- ``Codec`` instance must be one that encodes and decodes a full BSON
+  document, and not just, for example, a single BSON value like an
+  ``Int32``.
+
+By default, a ``MongoCollection`` is configured with ``Codec`` instances
+for three classes:
+
+- ``Document``
+- ``BsonDocument``
+- ``BasicDBObject``
+
+Applications are free to register ``Codec`` implementations
+for other classes by customizing the ``CodecRegistry``. New
+``CodecRegistry`` instances are configurable at the following levels:
+
+- In a ``MongoClient`` within ``MongoClientSettings``
+- In a ``MongoDatabase`` within its ``withCodecRegistry`` method
+- In a ``MongoCollection`` within its ``withCodecRegistry`` method
+
+Consider the case of encoding and decoding instances of the ``UUID``
+class. The driver by default encodes instances of ``UUID`` by using a
+byte ordering that is not compatible with other MongoDB drivers, and
+changing the default would be dangerous.
+
+It is possible for new applications that require interoperability across
+multiple drivers to be able to change that default, and they can do that
+by specifying a ``CodecRegistry``
+
+.. code-block:: java
+
+   // replaces the default UuidCodec to use the standard UUID representation
+   CodecRegistry codecRegistry = CodecRegistries.fromRegistries(
+       CodecRegistries.fromCodecs(new UuidCodec(UuidRepresentation.STANDARD)
+   ), MongoClientSettings.getDefaultCodecRegistry());
+    
+   // globally
+   MongoClientSettings settings = MongoClientSettings.builder()
+       .codecRegistry(codecRegistry).build();
+   MongoClient client = MongoClients.create(settings);
+    
+   // or per database
+   MongoDatabase database = client.getDatabase("mydb")
+       .withCodecRegistry(codecRegistry);
+    
+   // or per collection
+   MongoCollection<Document> collection = database.getCollection("mycoll")
+       .withCodecRegistry(codecRegistry);