MongoDB::GridFSBucket::UploadStream - phpMan

MongoDB::GridFSBucket::UploadStUser(Contributed Perl DocuMongoDB::GridFSBucket::UploadStream(3pm)

NAME
MongoDB::GridFSBucket::UploadStream - File handle abstraction for uploading

VERSION
version v2.2.2

SYNOPSIS
# OO API
$stream = $bucket->open_upload_stream("foo.txt");
$stream->print( $data );
$stream->close;
$id = $stream->id;

# Tied handle API
$fh = $stream->fh
print {$fh} $data;
close $fh;

DESCRIPTION
This class provides a file abstraction for uploading. You can stream data to an object of
this class via methods or via a tied-handle interface.

Writes are buffered and sent in chunk-size units. When "close" is called, all data will
be flushed to the GridFS Bucket and the newly created file will be visible.

ATTRIBUTES
chunk_size_bytes
The number of bytes per chunk. Defaults to the "chunk_size_bytes" of the originating
bucket object.

This will be stored in the "chunkSize" field of the file document on a successful upload.

filename
The filename to store the file under. Note that filenames are NOT necessarily unique.

This will be stored in the "filename" field of the file document on a successful upload.

metadata
An optional hashref for storing arbitrary metadata about the file.

If defined, this will be stored in the "metadata" field of the file document on a
successful upload.

content_type (DEPRECATED)
An optional MIME type. This field should only be used for backwards compatibility with
older GridFS implementations. New applications should store the content type in the
metadata hash if needed.

If defined, this will be stored in the "contentType" field of the file document on a
successful upload.

aliases (DEPRECATED)
An optional array of aliases. This field should only be used for backwards compatibility
with older GridFS implementations. New applications should store aliases in the metadata
hash if needed.

If defined, this will be stored in the "aliases" field of the file document on a
successful upload.

METHODS
id
$id = $stream->id;

The id of the file created by the stream. It will be stored in the "_id" field of the
file document on a successful upload. Some upload methods require specifying an id at
upload time. Defaults to a newly-generated BSON::OID or BSON codec specific equivalent.

fh
my $fh = $stream->fh;
print $fh, 'test data...';
close $fh

Returns a new file handle tied to this instance of UploadStream that can be operated on
with the built-in functions "print", "printf", "syswrite", "fileno" and "close".

Important notes:

Allowing one of these tied filehandles to fall out of scope will NOT cause close to be
called. This is due to the way tied file handles are implemented in Perl. For close to be
called implicitly, all tied filehandles and the original object must go out of scope.

Each file handle retrieved this way is tied back to the same object, so calling close on
multiple tied file handles and/or the original object will have the same effect as calling
close on the original object multiple times.

abort
$stream->abort;

Aborts the upload by deleting any chunks already uploaded to the database and closing the
stream.

close
$file_doc = $stream->close;

Closes the stream and flushes any remaining data to the database. Once this is done a file
document is created in the GridFS bucket, making the uploaded file visible in subsequent
queries or downloads.

On success, the file document hash reference is returned as a convenience.

Important notes:

o Calling close will also cause any tied file handles created for the stream to also
close.

o "close" will be automatically called when a stream object is destroyed. When called
this way, any errors thrown will not halt execution.

o Calling "close" repeatedly will warn.

fileno
if ( $stream->fileno ) { ... }

Works like the builtin "fileno", but it returns -1 if the stream is open and undef if
closed.

print
$stream->print(@data);

Works like the builtin "print".

printf
$stream->printf($format, @data);

Works like the builtin "printf".

syswrite
$stream->syswrite($buffer);
$stream->syswrite($buffer, $length);
$stream->syswrite($buffer, $length, $offset);

Works like the builtin "syswrite".

CAVEATS
Character encodings
All the writer methods (e.g. "print", "printf", etc.) send a binary representation of the
string input provided (or generated in the case of "printf"). Unless you explicitly
encode it to bytes, this will be the internal representation of the string in the Perl
interpreter. If you have ASCII characters, it will already be bytes. If you have any
characters above 0xff, it will be UTF-8 encoded codepoints. If you have characters
between 0x80 and 0xff and not higher, you might have either bytes or UTF-8 internally.

You are strongly encouraged to do your own character encoding with the Encode module or
equivalent and upload only bytes to GridFS.

AUTHORS
o David Golden <david AT mongodb.com>

o Rassi <rassi AT mongodb.com>

o Mike Friedman <friedo AT friedo.com>

o Kristina Chodorow <k.chodorow AT gmail.com>

o Florian Ragwitz <rafl AT debian.org>

This is free software, licensed under:

The Apache License, Version 2.0, January 2004

perl v5.30.3 2020-08-15 MongoDB::GridFSBucket::UploadStream(3pm)

Generated by $Id: phpMan.php,v 4.55 2007/09/05 04:42:51 chedong Exp $ Author: Che Dong
On Apache
Under GNU General Public License
2024-12-12 19:58 @3.138.69.145 CrawledBy Mozilla/5.0 AppleWebKit/537.36 (KHTML, like Gecko; compatible; ClaudeBot/1.0; +claudebot@anthropic.com)