1MongoDB::GridFSBucket::UUspelroaCdoSnttrreiabmu(t3e)d PeMrolngDooDcBu:m:eGnrtiadtFiSoBnucket::UploadStream(3)
2
3
4

NAME

6       MongoDB::GridFSBucket::UploadStream - File handle abstraction for
7       uploading
8

VERSION

10       version v2.2.2
11

SYNOPSIS

13           # OO API
14           $stream  = $bucket->open_upload_stream("foo.txt");
15           $stream->print( $data );
16           $stream->close;
17           $id = $stream->id;
18
19           # Tied handle API
20           $fh = $stream->fh
21           print {$fh} $data;
22           close $fh;
23

DESCRIPTION

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
29       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

ATTRIBUTES

34   chunk_size_bytes
35       The number of bytes per chunk.  Defaults to the "chunk_size_bytes" of
36       the originating bucket object.
37
38       This will be stored in the "chunkSize" field of the file document on a
39       successful upload.
40
41   filename
42       The filename to store the file under. Note that filenames are NOT
43       necessarily unique.
44
45       This will be stored in the "filename" field of the file document on a
46       successful upload.
47
48   metadata
49       An optional hashref for storing arbitrary metadata about the file.
50
51       If defined, this will be stored in the "metadata" field of the file
52       document on a successful upload.
53
54   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
59       If defined, this will be stored in the "contentType" field of the file
60       document on a successful upload.
61
62   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
67       If defined, this will be stored in the "aliases" field of the file
68       document on a successful upload.
69

METHODS

71   id
72           $id = $stream->id;
73
74       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
79   fh
80           my $fh = $stream->fh;
81           print $fh, 'test data...';
82           close $fh
83
84       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
88       Important notes:
89
90       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
95       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
100   abort
101           $stream->abort;
102
103       Aborts the upload by deleting any chunks already uploaded to the
104       database and closing the stream.
105
106   close
107           $file_doc = $stream->close;
108
109       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
113       On success, the file document hash reference is returned as a
114       convenience.
115
116       Important notes:
117
118       •   Calling close will also cause any tied file handles created for the
119           stream to also close.
120
121       •   "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
125       •   Calling "close" repeatedly will warn.
126
127   fileno
128           if ( $stream->fileno ) { ... }
129
130       Works like the builtin "fileno", but it returns -1 if the stream is
131       open and undef if closed.
132
133   print
134           $stream->print(@data);
135
136       Works like the builtin "print".
137
138   printf
139           $stream->printf($format, @data);
140
141       Works like the builtin "printf".
142
143   syswrite
144           $stream->syswrite($buffer);
145           $stream->syswrite($buffer, $length);
146           $stream->syswrite($buffer, $length, $offset);
147
148       Works like the builtin "syswrite".
149

CAVEATS

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
161       You are strongly encouraged to do your own character encoding with the
162       Encode module or equivalent and upload only bytes to GridFS.
163

AUTHORS

165       •   David Golden <david@mongodb.com>
166
167       •   Rassi <rassi@mongodb.com>
168
169       •   Mike Friedman <friedo@friedo.com>
170
171       •   Kristina Chodorow <k.chodorow@gmail.com>
172
173       •   Florian Ragwitz <rafl@debian.org>
174
176       This software is Copyright (c) 2020 by MongoDB, Inc.
177
178       This is free software, licensed under:
179
180         The Apache License, Version 2.0, January 2004
181
182
183
184perl v5.38.0                      2023-07M-o2n0goDB::GridFSBucket::UploadStream(3)
Impressum