NAME

       MongoDB::GridFS - A file storage abstraction (DEPRECATED)

VERSION

       version v1.8.1

SYNOPSIS

           my $grid = $database->get_gridfs;
           my $fh = IO::File->new("myfile", "r");
           $grid->insert($fh, {"filename" => "mydbfile"});

DESCRIPTION

       This class models a GridFS file store in a MongoDB database and provides an API for
       interacting with it.

       Generally, you never construct one of these directly with "new".  Instead, you call
       "get_gridfs" on a MongoDB::Database object.

USAGE

   API
       There are two interfaces for GridFS: a file-system/collection-like interface (insert,
       remove, drop, find_one) and a more general interface (get, put, delete).  Their
       functionality is the almost identical (get, put and delete are always safe ops, insert,
       remove, and find_one are optionally safe), using one over the other is a matter of
       preference.

   Error handling
       Unless otherwise explicitly documented, all methods throw exceptions if an error occurs.
       The error types are documented in MongoDB::Error.

       To catch and handle errors, the Try::Tiny and Safe::Isa modules are recommended:

           use Try::Tiny;
           use Safe::Isa; # provides $_isa

           try {
               $grid->get( $id )
           }
           catch {
               if ( $_->$_isa("MongoDB::TimeoutError" ) {
                   ...
               }
               else {
                   ...
               }
           };

       To retry failures automatically, consider using Try::Tiny::Retry.

ATTRIBUTES

   chunk_size
       The number of bytes per chunk.  Defaults to 261120 (255kb).

   read_preference
       A MongoDB::ReadPreference object.  It may be initialized with a string corresponding to
       one of the valid read preference modes or a hash reference that will be coerced into a new
       MongoDB::ReadPreference object.  By default it will be inherited from a MongoDB::Database
       object.

   write_concern
       A MongoDB::WriteConcern object.  It may be initialized with a hash reference that will be
       coerced into a new MongoDB::WriteConcern object.  By default it will be inherited from a
       MongoDB::Database object.

   max_time_ms
       Specifies the default maximum amount of time in milliseconds that the server should use
       for working on a query.

       Note: this will only be used for server versions 2.6 or greater, as that was when the
       $maxTimeMS meta-operator was introduced.

   bson_codec
       An object that provides the "encode_one" and "decode_one" methods, such as from
       MongoDB::BSON.  It may be initialized with a hash reference that will be coerced into a
       new MongoDB::BSON object.  By default it will be inherited from a MongoDB::Database
       object.

   prefix
       The prefix used for the collections.  Defaults to "fs".

METHODS

   get
           $file = $grid->get($id);

       Get a file from GridFS based on its _id.  Returns a MongoDB::GridFS::File.

       To retrieve a file based on metadata like "filename", use the "find_one" method instead.

   put
           $id = $grid->put($fh, $metadata);
           $id = $grid->put($fh, {filename => "pic.jpg"});

       Inserts a file into GridFS, adding a MongoDB::OID as the _id field if the field is not
       already defined.  This is a wrapper for "MongoDB::GridFS::insert", see that method below
       for more information.

       Returns the _id field.

   delete
           $grid->delete($id)

       Removes the file with the given _id.  Will die if the remove is unsuccessful.  Does not
       return anything on success.

   find_one
           $file = $grid->find_one({"filename" => "foo.txt"});
           $file = $grid->find_one($criteria, $fields);

       Returns a matching MongoDB::GridFS::File or undef.

   remove
           $grid->remove({"filename" => "foo.txt"});
           $grid->remove({"filename" => "foo.txt"}, $options);

       Cleanly removes files from the database.  $options is a hash of options for the remove.

       A hashref of options may be provided with the following keys:

       •   "just_one": If true, only one file matching the criteria will be removed.

       •   "safe": (DEPRECATED) If true, each remove will be checked for success and die on
           failure.  Set the "write_concern" attribute instead.

       This method doesn't return anything.

   insert
           $id = $gridfs->insert($fh);
           $id = $gridfs->insert($fh, $metadata);
           $id = $gridfs->insert($fh, $metadata, $options);

           $id = $gridfs->insert($fh, {"content-type" => "text/html"});

       Reads from a file handle into the database.  Saves the file with the given metadata.  The
       file handle must be readable.

       A hashref of options may be provided with the following keys:

       •   "safe": (DEPRECATED) Will do safe inserts and check the MD5 hash calculated by the
           database against an MD5 hash calculated by the local filesystem.  If the two hashes do
           not match, then the chunks already inserted will be removed and the program will die.
           Set the "write_concern" attribute instead.

       Because "MongoDB::GridFS::insert" takes a file handle, it can be used to insert very long
       strings into the database (as well as files).  $fh must be a FileHandle (not just the
       native file handle type), so you can insert a string with:

           # open the string like a file
           open($basic_fh, '<', \$very_long_string);

           # turn the file handle into a FileHandle
           $fh = FileHandle->new;
           $fh->fdopen($basic_fh, 'r');

           $gridfs->insert($fh);

   drop
           $grid->drop;

       Removes all files' metadata and contents.

   all
           @files = $grid->all;

       Returns a list of the files in the database as MongoDB::GridFS::File objects.

DEPRECATION

       Note: This class has been deprecated in favor of MongoDB::GridFSBucket, which implements
       the new, driver-standard GridFS API.  It is also faster and more flexible than this class.
       This class will be removed in a future release and you are encouraged to migrate your
       applications to MongoDB::GridFSBucket.

SEE ALSO

       Core documentation on GridFS: <http://dochub.mongodb.org/core/gridfs>.

AUTHORS

       •   David Golden <david@mongodb.com>

       •   Rassi <rassi@mongodb.com>

       •   Mike Friedman <friedo@friedo.com>

       •   Kristina Chodorow <k.chodorow@gmail.com>

       •   Florian Ragwitz <rafl@debian.org>

COPYRIGHT AND LICENSE

       This software is Copyright (c) 2018 by MongoDB, Inc.

       This is free software, licensed under:

         The Apache License, Version 2.0, January 2004