1MongoDB::GridFSBucket::UUspelroaCdoSnttrreiabmu(t3e)d PeMrolngDooDcBu:m:eGnrtiadtFiSoBnucket::UploadStream(3)
2
6 MongoDB::GridFSBucket::UploadStream - File handle abstraction for
7 uploading
8
10 version v2.2.2
11
13 # OO API
14 $stream = $bucket->open_upload_stream("foo.txt");
15 $stream->print( $data );
16 $stream->close;
17 $id = $stream->id;
18 # Tied handle API
20 $fh = $stream->fh
21 print {$fh} $data;
22 close $fh;
23
25 This class provides a file abstraction for uploading. You can stream
26 data to an object of this class via methods or via a tied-handle
27 interface.
28 Writes are buffered and sent in chunk-size units. When "close" is
30 called, all data will be flushed to the GridFS Bucket and the newly
31 created file will be visible.
32
34 chunk_size_bytes
35 The number of bytes per chunk. Defaults to the "chunk_size_bytes" of
36 the originating bucket object.
37 This will be stored in the "chunkSize" field of the file document on a
39 successful upload.
40 filename
42 The filename to store the file under. Note that filenames are NOT
43 necessarily unique.
44 This will be stored in the "filename" field of the file document on a
46 successful upload.
47 metadata
49 An optional hashref for storing arbitrary metadata about the file.
50 If defined, this will be stored in the "metadata" field of the file
52 document on a successful upload.
53 content_type (DEPRECATED)
55 An optional MIME type. This field should only be used for backwards
56 compatibility with older GridFS implementations. New applications
57 should store the content type in the metadata hash if needed.
58 If defined, this will be stored in the "contentType" field of the file
60 document on a successful upload.
61 aliases (DEPRECATED)
63 An optional array of aliases. This field should only be used for
64 backwards compatibility with older GridFS implementations. New
65 applications should store aliases in the metadata hash if needed.
66 If defined, this will be stored in the "aliases" field of the file
68 document on a successful upload.
69
71 id
72 $id = $stream->id;
73 The id of the file created by the stream. It will be stored in the
75 "_id" field of the file document on a successful upload. Some upload
76 methods require specifying an id at upload time. Defaults to a newly-
77 generated BSON::OID or BSON codec specific equivalent.
78 fh
80 my $fh = $stream->fh;
81 print $fh, 'test data...';
82 close $fh
83 Returns a new file handle tied to this instance of UploadStream that
85 can be operated on with the built-in functions "print", "printf",
86 "syswrite", "fileno" and "close".
87 Important notes:
89 Allowing one of these tied filehandles to fall out of scope will NOT
91 cause close to be called. This is due to the way tied file handles are
92 implemented in Perl. For close to be called implicitly, all tied
93 filehandles and the original object must go out of scope.
94 Each file handle retrieved this way is tied back to the same object, so
96 calling close on multiple tied file handles and/or the original object
97 will have the same effect as calling close on the original object
98 multiple times.
99 abort
101 $stream->abort;
102 Aborts the upload by deleting any chunks already uploaded to the
104 database and closing the stream.
105 close
107 $file_doc = $stream->close;
108 Closes the stream and flushes any remaining data to the database. Once
110 this is done a file document is created in the GridFS bucket, making
111 the uploaded file visible in subsequent queries or downloads.
112 On success, the file document hash reference is returned as a
114 convenience.
115 Important notes:
117 • Calling close will also cause any tied file handles created for the
119 stream to also close.
120 • "close" will be automatically called when a stream object is
122 destroyed. When called this way, any errors thrown will not halt
123 execution.
124 • Calling "close" repeatedly will warn.
126 fileno
128 if ( $stream->fileno ) { ... }
129 Works like the builtin "fileno", but it returns -1 if the stream is
131 open and undef if closed.
132 print
134 $stream->print(@data);
135 Works like the builtin "print".
137 printf
139 $stream->printf($format, @data);
140 Works like the builtin "printf".
142 syswrite
144 $stream->syswrite($buffer);
145 $stream->syswrite($buffer, $length);
146 $stream->syswrite($buffer, $length, $offset);
147 Works like the builtin "syswrite".
149
151 Character encodings
152 All the writer methods (e.g. "print", "printf", etc.) send a binary
153 representation of the string input provided (or generated in the case
154 of "printf"). Unless you explicitly encode it to bytes, this will be
155 the internal representation of the string in the Perl interpreter. If
156 you have ASCII characters, it will already be bytes. If you have any
157 characters above 0xff, it will be UTF-8 encoded codepoints. If you
158 have characters between 0x80 and 0xff and not higher, you might have
159 either bytes or UTF-8 internally.
160 You are strongly encouraged to do your own character encoding with the
162 Encode module or equivalent and upload only bytes to GridFS.
163
165 • David Golden <david@mongodb.com>
166 • Rassi <rassi@mongodb.com>
168 • Mike Friedman <friedo@friedo.com>
170 • Kristina Chodorow <k.chodorow@gmail.com>
172 • Florian Ragwitz <rafl@debian.org>
174
176 This software is Copyright (c) 2020 by MongoDB, Inc.
177 This is free software, licensed under:
179 The Apache License, Version 2.0, January 2004
181perl v5.38.0 2023-07M-o2n0goDB::GridFSBucket::UploadStream(3)