Merge pull request #17 from rustagir/DOCSP-37861-gridfs

DOCSP-37861: gridfs tutorial

Author: rustagir

source/tutorials.txt

@@ -16,4 +16,5 @@ Tutorials
    /tutorials/change-stream/
    /tutorials/text-search/
    /tutorials/geo/
+   /tutorials/gridfs/
 

source/tutorials/gridfs.txt

@@ -0,0 +1,221 @@
+.. _javars-gridfs:
+
+======
+GridFS
+======
+
+.. contents:: On this page
+   :local:
+   :backlinks: none
+   :depth: 2
+   :class: singlecol
+
+GridFS is a specification for storing and retrieving files that
+exceed the BSON document size limit of 16 MB. Instead of storing a large
+file in a single document, GridFS divides a file into parts, or chunks, and
+stores each of those chunks as separate documents.
+
+When you query a GridFS store for a file, the driver reassembles the
+chunks as needed.
+
+The code examples in this guide come from the `GridFSTour.java
+<{+driver-source-gh+}/blob/master/driver-reactive-streams/src/examples/reactivestreams/gridfs/GridFSTour.java>`__
+file in the driver source code GitHub repository.
+
+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.MongoDatabase;
+    
+   import com.mongodb.client.gridfs.model.*;
+   import com.mongodb.reactivestreams.client.gridfs.*;
+    
+   import org.bson.Document;
+   import org.bson.types.ObjectId;
+    
+   import java.io.FileNotFoundException;
+   import java.io.IOException;
+   import java.nio.Buffer;
+   import java.nio.ByteBuffer;
+   import java.nio.charset.StandardCharsets;
+    
+   import static com.mongodb.client.model.Filters.eq;
+   import static reactivestreams.helpers.PublisherHelpers.toPublisher;
+
+.. 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 MongoDB deployment and declare and define
+a ``MongoDatabase`` instance.
+
+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.
+
+Create a GridFS Bucket
+----------------------
+
+GridFS stores files in two collections:
+
+- ``chunks``: stores the file chunks
+- ``files``: stores file metadata
+
+The two collections are in a common bucket and the collection names
+are prefixed with the bucket name.
+
+The driver provides the ``GridFSBuckets.create()`` method to
+create ``GridFSBucket`` instances:
+
+.. code-block:: java
+
+   MongoDatabase myDatabase = mongoClient.getDatabase("mydb");
+    
+   // Create a gridFSBucket using the default bucket name "fs"
+   GridFSBucket gridFSBucket = GridFSBuckets.create(myDatabase);
+
+You can pass a bucket name to the ``GridFSBuckets.create()`` method:
+
+.. code-block:: java
+
+   // Create a gridFSBucket with a custom bucket name "files"
+   GridFSBucket gridFSFilesBucket = GridFSBuckets.create(myDatabase, "files");
+
+.. note::
+
+   GridFS automatically creates indexes on the ``files`` and ``chunks``
+   collections when you upload data to the GridFS bucket.
+
+Upload to GridFS
+----------------
+
+The ``GridFSBucket.uploadFromPublisher()`` method reads the contents
+of ``Publisher<ByteBuffer>`` and saves it to the ``GridFSBucket`` instance.
+
+You can use the ``GridFSUploadOptions`` type to configure the chunk size
+or include additional metadata.
+
+The following example uploads the contents of a
+``Publisher<ByteBuffer>`` into ``GridFSBucket``:
+
+.. code-block:: java
+
+   // Get the input publisher
+   Publisher<ByteBuffer> publisherToUploadFrom = toPublisher(
+       ByteBuffer
+           .wrap("MongoDB Tutorial..".getBytes(StandardCharsets.UTF_8))
+   );
+    
+   // Create some custom options
+   GridFSUploadOptions options = new GridFSUploadOptions()
+       .chunkSizeBytes(1024)
+       .metadata(new Document("type", "presentation"));
+    
+   ObservableSubscriber<ObjectId> uploadSubscriber = new OperationSubscriber<>();
+   gridFSBucket.uploadFromPublisher("mongodb-tutorial", publisherToUploadFrom, options).subscribe(uploadSubscriber);
+   ObjectId fileId = uploadSubscriber.get().get(0);
+
+Find Files Stored in GridFS
+---------------------------
+
+To find the files stored in the ``GridFSBucket``, use the ``find()``
+method.
+
+The following example prints out the filename of each file stored:
+
+.. code-block:: java
+
+   ConsumerSubscriber<GridFSFile> filesSubscriber = new ConsumerSubscriber<>(gridFSFile ->
+       System.out.println(" - " + gridFSFile.getFilename()));
+   gridFSBucket.find().subscribe(filesSubscriber);
+   filesSubscriber.await();
+
+You can also provide a custom filter to limit the results returned.
+The following example prints out the filenames of all files in which the
+``contentType`` value is an ``image/png`` value in the user-defined metadata
+document:
+
+.. code-block:: java
+
+   filesSubscriber = new ConsumerSubscriber<>(gridFSFile -> System.out.println("Found: " + gridFSFile.getFilename()));
+   gridFSBucket.find(eq("metadata.contentType", "image/png")).subscribe(filesSubscriber);
+   filesSubscriber.await();
+
+Download from GridFS
+--------------------
+
+The ``downloadToPublisher()`` method returns a ``Publisher<ByteBuffer>``
+that reads the contents from MongoDB.
+
+To download a file by its file ``_id``, pass the ``_id`` to the method.
+The following example downloads a file by its file ``_id``:
+
+.. code-block:: java
+
+   ObjectId fileId;
+   ObservableSubscriber<ByteBuffer> downloadSubscriber = new OperationSubscriber<>();
+   gridFSBucket.downloadToPublisher(fileId).subscribe(downloadSubscriber);
+
+If you don't know the ``_id`` of the file but know the filename, then you
+can pass the filename to the ``downloadToPublisher()`` method. By
+default, it will download the latest version of the file. Use the
+``GridFSDownloadOptions`` class to configure which version to download.
+
+The following example downloads the original version of the file named
+``mongodb-tutorial``:
+
+.. code-block:: java
+
+   GridFSDownloadOptions downloadOptions = new GridFSDownloadOptions().revision(0);
+   downloadSubscriber = new OperationSubscriber<>();
+   gridFSBucket.downloadToPublisher("mongodb-tutorial", downloadOptions).subscribe(downloadSubscriber);
+
+Rename Files
+------------
+
+If you need to rename a file, then use the ``rename()`` method.
+
+The following example renames a file to ``mongodbTutorial``:
+
+.. code-block:: java
+
+   ObjectId fileId; //ObjectId of a file uploaded to GridFS
+   gridFSBucket.rename(fileId, "mongodbTutorial").subscribe(new ObservableSubscriber<Void>());
+
+.. note::
+
+   The ``rename()`` method requires an ``ObjectId`` rather than a ``filename`` to
+   ensure the correct file is renamed.
+   
+   To rename multiple revisions of the same filename, first retrieve the
+   full list of files. Then, for every file that should be renamed,
+   run ``rename()`` with the corresponding ``_id``.
+
+Delete Files
+------------
+
+To delete a file from the ``GridFSBucket``, use the ``delete()`` method.
+
+The following example deletes a file from the ``GridFSBucket``:
+
+.. code-block:: java
+
+   ObjectId fileId; //ObjectId of a file uploaded to GridFS
+   gridFSBucket.delete(fileId).subscribe(new ObservableSubscriber<Void>());