DOCSP-38209: gridfs (#20)

* DOCSP-38209: gridfs

* clean up code snippet

Author: rustagir

source/tutorials.txt

@@ -16,8 +16,8 @@ Tutorials
    /tutorials/change-stream/
    /tutorials/text-search/
    /tutorials/geospatial/
+   /tutorials/gridfs/
 
-.. /tutorials/gridfs/
 .. /tutorials/command/
 
 - :ref:`scala-connect`
@@ -30,6 +30,6 @@ Tutorials
 - :ref:`scala-changestream`
 - :ref:`scala-text-search`
 - :ref:`scala-geospatial`
+- :ref:`scala-gridfs`
 
-.. - :ref:`scala-gridfs`
 .. - :ref:`scala-run-command`

source/tutorials/gridfs.txt

@@ -0,0 +1,212 @@
+.. _scala-gridfs:
+
+======
+GridFS
+======
+
+.. facet::
+   :name: genre
+   :values: reference
+
+.. meta::
+   :keywords: code example, large file, storage
+
+.. 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.scala
+<{+driver-source-gh+}/blob/master/driver-scala/src/integration/scala/tour/GridFSTour.scala>`__
+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:: scala
+
+   import java.nio.ByteBuffer
+   import java.nio.charset.StandardCharsets
+   
+   import org.mongodb.scala._
+   import org.mongodb.scala.bson.BsonObjectId
+   import org.mongodb.scala.gridfs._
+   import org.mongodb.scala.model.Filters
+   
+   import tour.Helpers._
+   
+   import scala.util.Success
+
+.. include:: /includes/obs-note.rst
+
+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:: scala
+
+   val mongoClient: MongoClient = MongoClient()
+
+To learn more about connecting to MongoDB deployments,
+see the :ref:`scala-connect` guide.
+
+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 ``GridFSBucket()`` method to
+create ``GridFSBucket`` instances:
+
+.. code-block:: scala
+
+   val myDatabase = mongoClient.getDatabase("mydb")
+   
+   // Create a gridFSBucket using the default bucket name "fs"
+   val gridFSBucket = GridFSBucket(myDatabase)
+
+You can pass a bucket name to the ``GridFSBucket()`` method:
+
+.. code-block:: scala
+
+   // Create a gridFSBucket with a custom bucket name "files"
+   val gridFSFilesBucket = GridFSBucket(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.uploadFromObservable()`` method reads the contents
+of an ``Observable[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
+``Observable[ByteBuffer]`` into ``GridFSBucket``:
+
+.. code-block:: scala
+
+   // Get the input stream
+   val observableToUploadFrom: Observable[ByteBuffer] = Observable(
+     Seq(ByteBuffer.wrap("MongoDB Tutorial".getBytes(StandardCharsets.UTF_8)))
+   )
+   
+   // Create some custom options
+   val options: GridFSUploadOptions = new GridFSUploadOptions()
+       .chunkSizeBytes(358400)
+       .metadata(Document("type" -> "presentation"))
+   
+   val fileId: BsonObjectId = gridFSBucket
+       .uploadFromObservable("mongodb-tutorial", observableToUploadFrom, options)
+       .headResult()
+
+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:: scala
+
+   gridFSBucket.find().results().foreach(file => println(s" - ${file.getFilename}"))
+
+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:: scala
+
+   gridFSBucket
+     .find(Filters.equal("metadata.contentType", "image/png"))
+     .results()
+     .foreach(file => println(s" > ${file.getFilename}"))
+
+Download from GridFS
+--------------------
+
+The ``downloadToObservable()`` method returns an ``Observable[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:: scala
+
+   val downloadById = gridFSBucket.downloadToObservable(fileId).results()
+
+If you don't know the ``_id`` of the file but know the filename, then you
+can pass the filename to the ``downloadToObservable()`` 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:: scala
+
+   val downloadOptions: GridFSDownloadOptions = new GridFSDownloadOptions().revision(0)
+   val downloadByName = gridFSBucket.downloadToObservable("mongodb-tutorial", downloadOptions).results()
+
+Rename Files
+------------
+
+If you need to rename a file, then use the ``rename()`` method.
+
+The following example renames a file to ``mongodbTutorial``:
+
+.. code-block:: scala
+
+   val fileId: ObjectId = ... // ObjectId of a file uploaded to GridFS
+   gridFSBucket.rename(fileId, "mongodbTutorial").printResults()
+
+.. 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:: scala
+
+   val fileId: ObjectId = ... //ObjectId of a file uploaded to GridFS
+   gridFSBucket.delete(fileId).printResults()