GODRIVER-1381 Add GridFS examples (#272)

Divjot Arora · web-flow · commit afd796b6135c · 2020-01-15T15:35:50.000-05:00
diff --git a/mongo/gridfs/bucket.go b/mongo/gridfs/bucket.go
@@ -137,13 +137,19 @@ func (b *Bucket) OpenUploadStreamWithID(fileID interface{}, filename string, opt
 }
 
 // UploadFromStream creates a fileID and uploads a file given a source stream.
+//
+// If this upload requires a custom write deadline to be set on the bucket, it cannot be done concurrently with other
+// write operations operations on this bucket that also require a custom deadline.
 func (b *Bucket) UploadFromStream(filename string, source io.Reader, opts ...*options.UploadOptions) (primitive.ObjectID, error) {
 	fileID := primitive.NewObjectID()
 	err := b.UploadFromStreamWithID(fileID, filename, source, opts...)
 	return fileID, err
 }
 
 // UploadFromStreamWithID uploads a file given a source stream.
+//
+// If this upload requires a custom write deadline to be set on the bucket, it cannot be done concurrently with other
+// write operations operations on this bucket that also require a custom deadline.
 func (b *Bucket) UploadFromStreamWithID(fileID interface{}, filename string, source io.Reader, opts ...*options.UploadOptions) error {
 	us, err := b.OpenUploadStreamWithID(fileID, filename, opts...)
 	if err != nil {
@@ -191,6 +197,9 @@ func (b *Bucket) OpenDownloadStream(fileID interface{}) (*DownloadStream, error)
 
 // DownloadToStream downloads the file with the specified fileID and writes it to the provided io.Writer.
 // Returns the number of bytes written to the steam and an error, or nil if there was no error.
+//
+// If this download requires a custom read deadline to be set on the bucket, it cannot be done concurrently with other
+// read operations operations on this bucket that also require a custom deadline.
 func (b *Bucket) DownloadToStream(fileID interface{}, stream io.Writer) (int64, error) {
 	ds, err := b.OpenDownloadStream(fileID)
 	if err != nil {
@@ -221,6 +230,9 @@ func (b *Bucket) OpenDownloadStreamByName(filename string, opts ...*options.Name
 }
 
 // DownloadToStreamByName downloads the file with the given name to the given io.Writer.
+//
+// If this download requires a custom read deadline to be set on the bucket, it cannot be done concurrently with other
+// read operations operations on this bucket that also require a custom deadline.
 func (b *Bucket) DownloadToStreamByName(filename string, stream io.Writer, opts ...*options.NameOptions) (int64, error) {
 	ds, err := b.OpenDownloadStreamByName(filename, opts...)
 	if err != nil {
@@ -231,6 +243,9 @@ func (b *Bucket) DownloadToStreamByName(filename string, stream io.Writer, opts
 }
 
 // Delete deletes all chunks and metadata associated with the file with the given file ID.
+//
+// If this operation requires a custom write deadline to be set on the bucket, it cannot be done concurrently with other
+// write operations operations on this bucket that also require a custom deadline.
 func (b *Bucket) Delete(fileID interface{}) error {
 	// delete document in files collection and then chunks to minimize race conditions
 
@@ -256,6 +271,9 @@ func (b *Bucket) Delete(fileID interface{}) error {
 }
 
 // Find returns the files collection documents that match the given filter.
+//
+// If this download requires a custom read deadline to be set on the bucket, it cannot be done concurrently with other
+// read operations operations on this bucket that also require a custom deadline.
 func (b *Bucket) Find(filter interface{}, opts ...*options.GridFSFindOptions) (*mongo.Cursor, error) {
 	ctx, cancel := deadlineContext(b.readDeadline)
 	if cancel != nil {
@@ -287,6 +305,9 @@ func (b *Bucket) Find(filter interface{}, opts ...*options.GridFSFindOptions) (*
 }
 
 // Rename renames the stored file with the specified file ID.
+//
+// If this operation requires a custom write deadline to be set on the bucket, it cannot be done concurrently with other
+// write operations operations on this bucket that also require a custom deadline
 func (b *Bucket) Rename(fileID interface{}, newFilename string) error {
 	ctx, cancel := deadlineContext(b.writeDeadline)
 	if cancel != nil {
@@ -313,6 +334,9 @@ func (b *Bucket) Rename(fileID interface{}, newFilename string) error {
 }
 
 // Drop drops the files and chunks collections associated with this bucket.
+//
+// If this operation requires a custom write deadline to be set on the bucket, it cannot be done concurrently with other
+// write operations operations on this bucket that also require a custom deadline
 func (b *Bucket) Drop() error {
 	ctx, cancel := deadlineContext(b.writeDeadline)
 	if cancel != nil {
diff --git a/mongo/gridfs/doc.go b/mongo/gridfs/doc.go
@@ -0,0 +1,35 @@
+// Copyright (C) MongoDB, Inc. 2017-present.
+//
+// Licensed under the Apache License, Version 2.0 (the "License"); you may
+// not use this file except in compliance with the License. You may obtain
+// a copy of the License at http://www.apache.org/licenses/LICENSE-2.0
+
+// Package gridfs provides a MongoDB GridFS API. See https://docs.mongodb.com/manual/core/gridfs/ for more
+// information about GridFS and its use cases.
+//
+// Buckets
+//
+// The main type defined in this package is Bucket. A Bucket wraps a mongo.Database instance and operates on two
+// collections in the database. The first is the files collection, which contains one metadata document per file stored
+// in the bucket. This collection is named "<bucket name>.files". The second is the chunks collection, which contains
+// chunks of files. This collection is named "<bucket name>.chunks".
+//
+// Uploading a File
+//
+// Files can be uploaded in two ways:
+// 	1. OpenUploadStream/OpenUploadStreamWithID - These methods return an UploadStream instance. UploadStream
+// 	implements the io.Writer interface and the Write() method can be used to upload a file to the database.
+//
+//	2. UploadFromStream/UploadFromStreamWithID - These methods take an io.Reader, which represents the file to
+// 	upload. They internally create a new UploadStream and close it once the operation is complete.
+//
+// Downloading a File
+//
+// Similar to uploads, files can be downloaded in two ways:
+//	1. OpenDownloadStream/OpenDownloadStreamByName - These methods return a DownloadStream instance. DownloadStream
+//	implements the io.Reader interface. A file can be read either using the Read() method or any standard library
+//	methods that reads from an io.Reader such as io.Copy.
+//
+//	2. DownloadToStream/DownloadToStreamByName - These methods take an io.Writer, which represents the download
+// 	destination. They internally create a new DownloadStream and close it once the operation is complete.
+package gridfs
diff --git a/mongo/gridfs/gridfs_examples_test.go b/mongo/gridfs/gridfs_examples_test.go
@@ -0,0 +1,153 @@
+// Copyright (C) MongoDB, Inc. 2017-present.
+//
+// Licensed under the Apache License, Version 2.0 (the "License"); you may
+// not use this file except in compliance with the License. You may obtain
+// a copy of the License at http://www.apache.org/licenses/LICENSE-2.0
+
+package gridfs_test
+
+import (
+	"bytes"
+	"context"
+	"fmt"
+	"io"
+	"log"
+	"time"
+
+	"go.mongodb.org/mongo-driver/bson"
+	"go.mongodb.org/mongo-driver/bson/primitive"
+	"go.mongodb.org/mongo-driver/mongo/gridfs"
+	"go.mongodb.org/mongo-driver/mongo/options"
+)
+
+func ExampleBucket_OpenUploadStream() {
+	var fileContent []byte
+	var bucket *gridfs.Bucket
+
+	// Specify the Metadata option to include a "metadata" field in the files collection document.
+	uploadOpts := options.GridFSUpload().SetMetadata(bson.D{{"metadata tag", "tag"}})
+	uploadStream, err := bucket.OpenUploadStream("filename", uploadOpts)
+	if err != nil {
+		log.Fatal(err)
+	}
+	defer func() {
+		if err = uploadStream.Close(); err != nil {
+			log.Fatal(err)
+		}
+	}()
+
+	// Use SetWriteDeadline to force a timeout if the upload does not succeed in 2 seconds.
+	if err = uploadStream.SetWriteDeadline(time.Now().Add(2 * time.Second)); err != nil {
+		log.Fatal(err)
+	}
+
+	if _, err = uploadStream.Write(fileContent); err != nil {
+		log.Fatal(err)
+	}
+}
+
+func ExampleBucket_UploadFromStream() {
+	var fileContent []byte
+	var bucket *gridfs.Bucket
+
+	// Specify the Metadata option to include a "metadata" field in the files collection document.
+	uploadOpts := options.GridFSUpload().SetMetadata(bson.D{{"metadata tag", "tag"}})
+	fileID, err := bucket.UploadFromStream("filename", bytes.NewBuffer(fileContent), uploadOpts)
+	if err != nil {
+		log.Fatal(err)
+	}
+
+	fmt.Printf("new file created with ID %s", fileID)
+}
+
+func ExampleBucket_OpenDownloadStream() {
+	var bucket *gridfs.Bucket
+	var fileID primitive.ObjectID
+
+	downloadStream, err := bucket.OpenDownloadStream(fileID)
+	if err != nil {
+		log.Fatal(err)
+	}
+	defer func() {
+		if err := downloadStream.Close(); err != nil {
+			log.Fatal(err)
+		}
+	}()
+
+	// Use SetReadDeadline to force a timeout if the download does not succeed in 2 seconds.
+	if err = downloadStream.SetReadDeadline(time.Now().Add(2 * time.Second)); err != nil {
+		log.Fatal(err)
+	}
+
+	fileBuffer := bytes.NewBuffer(nil)
+	if _, err := io.Copy(fileBuffer, downloadStream); err != nil {
+		log.Fatal(err)
+	}
+}
+
+func ExampleBucket_DownloadToStream() {
+	var bucket *gridfs.Bucket
+	var fileID primitive.ObjectID
+
+	fileBuffer := bytes.NewBuffer(nil)
+	if _, err := bucket.DownloadToStream(fileID, fileBuffer); err != nil {
+		log.Fatal(err)
+	}
+}
+
+func ExampleBucket_Delete() {
+	var bucket *gridfs.Bucket
+	var fileID primitive.ObjectID
+
+	if err := bucket.Delete(fileID); err != nil {
+		log.Fatal(err)
+	}
+}
+
+func ExampleBucket_Find() {
+	var bucket *gridfs.Bucket
+
+	// Specify a filter to find all files with a length greater than 1000 bytes.
+	filter := bson.D{
+		{"length", bson.D{{"$gt", 1000}}},
+	}
+	cursor, err := bucket.Find(filter)
+	if err != nil {
+		log.Fatal(err)
+	}
+	defer func() {
+		if err := cursor.Close(context.TODO()); err != nil {
+			log.Fatal(err)
+		}
+	}()
+
+	type gridfsFile struct {
+		Name   string `bson:"filename"`
+		Length int64  `bson:"length"`
+	}
+	var foundFiles []gridfsFile
+	if err = cursor.All(context.TODO(), &foundFiles); err != nil {
+		log.Fatal(err)
+	}
+
+	for _, file := range foundFiles {
+		fmt.Printf("filename: %s, length: %d\n", file.Name, file.Length)
+	}
+}
+
+func ExampleBucket_Rename() {
+	var bucket *gridfs.Bucket
+	var fileID primitive.ObjectID
+
+	if err := bucket.Rename(fileID, "new file name"); err != nil {
+		log.Fatal(err)
+	}
+}
+
+func ExampleBucket_Drop() {
+	var bucket *gridfs.Bucket
+
+	if err := bucket.Drop(); err != nil {
+		log.Fatal(err)
+	}
+}
diff --git a/mongo/gridfs/upload_stream.go b/mongo/gridfs/upload_stream.go
@@ -26,7 +26,9 @@ const UploadBufferSize = 16 * 1024 * 1024 // 16 MiB
 // ErrStreamClosed is an error returned if an operation is attempted on a closed/aborted stream.
 var ErrStreamClosed = errors.New("stream is closed or aborted")
 
-// UploadStream is used to upload files in chunks.
+// UploadStream is used to upload a file in chunks. This type implements the io.Writer interface and a file can be
+// uploaded using the Write method. After an upload is complete, the Close method must be called to write file
+// metadata.
 type UploadStream struct {
 	*Upload // chunk size and metadata
 	FileID  interface{}
@@ -55,7 +57,7 @@ func newUploadStream(upload *Upload, fileID interface{}, filename string, chunks
 	}
 }
 
-// Close closes this upload stream.
+// Close writes file metadata to the files collection and cleans up any resources associated with the UploadStream.
 func (us *UploadStream) Close() error {
 	if us.closed {
 		return ErrStreamClosed
