Current File : /home/opti/optisoftcom-new/perl/usr/man/man3/MongoDB::GridFSBucket::UploadStream.3pm
.\" Automatically generated by Pod::Man 2.27 (Pod::Simple 3.28)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings. \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote. \*(C+ will
.\" give a nicer C++. Capital omega is used to do unbreakable dashes and
.\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
. ds -- \(*W-
. ds PI pi
. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
. ds L" ""
. ds R" ""
. ds C` ""
. ds C' ""
'br\}
.el\{\
. ds -- \|\(em\|
. ds PI \(*p
. ds L" ``
. ds R" ''
. ds C`
. ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el .ds Aq '
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD. Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{
. if \nF \{
. de IX
. tm Index:\\$1\t\\n%\t"\\$2"
..
. if !\nF==2 \{
. nr % 0
. nr F 2
. \}
. \}
.\}
.rr rF
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear. Run. Save yourself. No user-serviceable parts.
. \" fudge factors for nroff and troff
.if n \{\
. ds #H 0
. ds #V .8m
. ds #F .3m
. ds #[ \f1
. ds #] \fP
.\}
.if t \{\
. ds #H ((1u-(\\\\n(.fu%2u))*.13m)
. ds #V .6m
. ds #F 0
. ds #[ \&
. ds #] \&
.\}
. \" simple accents for nroff and troff
.if n \{\
. ds ' \&
. ds ` \&
. ds ^ \&
. ds , \&
. ds ~ ~
. ds /
.\}
.if t \{\
. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
. \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
. \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
. \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
. ds : e
. ds 8 ss
. ds o a
. ds d- d\h'-1'\(ga
. ds D- D\h'-1'\(hy
. ds th \o'bp'
. ds Th \o'LP'
. ds ae ae
. ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "MongoDB::GridFSBucket::UploadStream 3"
.TH MongoDB::GridFSBucket::UploadStream 3 "2018-11-30" "perl v5.16.3" "User Contributed Perl Documentation"
.\" For nroff, turn off justification. Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
MongoDB::GridFSBucket::UploadStream \- File handle abstraction for uploading
.SH "VERSION"
.IX Header "VERSION"
version v2.0.2
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 5
\& # 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;
.Ve
.SH "DESCRIPTION"
.IX Header "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.
.PP
Writes are buffered and sent in chunk-size units. When \f(CW\*(C`close\*(C'\fR is called,
all data will be flushed to the GridFS Bucket and the newly created file
will be visible.
.SH "ATTRIBUTES"
.IX Header "ATTRIBUTES"
.SS "chunk_size_bytes"
.IX Subsection "chunk_size_bytes"
The number of bytes per chunk. Defaults to the \f(CW\*(C`chunk_size_bytes\*(C'\fR of the
originating bucket object.
.PP
This will be stored in the \f(CW\*(C`chunkSize\*(C'\fR field of the file document on
a successful upload.
.SS "filename"
.IX Subsection "filename"
The filename to store the file under. Note that filenames are \s-1NOT\s0 necessarily unique.
.PP
This will be stored in the \f(CW\*(C`filename\*(C'\fR field of the file document on
a successful upload.
.SS "metadata"
.IX Subsection "metadata"
An optional hashref for storing arbitrary metadata about the file.
.PP
If defined, this will be stored in the \f(CW\*(C`metadata\*(C'\fR field of the file
document on a successful upload.
.SS "content_type (\s-1DEPRECATED\s0)"
.IX Subsection "content_type (DEPRECATED)"
An optional \s-1MIME\s0 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.
.PP
If defined, this will be stored in the \f(CW\*(C`contentType\*(C'\fR field of the file
document on a successful upload.
.SS "aliases (\s-1DEPRECATED\s0)"
.IX Subsection "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.
.PP
If defined, this will be stored in the \f(CW\*(C`aliases\*(C'\fR field of the file
document on a successful upload.
.SH "METHODS"
.IX Header "METHODS"
.SS "id"
.IX Subsection "id"
.Vb 1
\& $id = $stream\->id;
.Ve
.PP
The id of the file created by the stream. It will be stored in the \f(CW\*(C`_id\*(C'\fR
field of the file document on a successful upload. Some upload methods
require specifying an id at upload time. Defaults to a newly-generated
\&\s-1BSON::OID\s0 or \s-1BSON\s0 codec specific equivalent.
.SS "fh"
.IX Subsection "fh"
.Vb 3
\& my $fh = $stream\->fh;
\& print $fh, \*(Aqtest data...\*(Aq;
\& close $fh
.Ve
.PP
Returns a new file handle tied to this instance of UploadStream that can be
operated on with the built-in functions \f(CW\*(C`print\*(C'\fR, \f(CW\*(C`printf\*(C'\fR, \f(CW\*(C`syswrite\*(C'\fR,
\&\f(CW\*(C`fileno\*(C'\fR and \f(CW\*(C`close\*(C'\fR.
.PP
\&\fBImportant notes\fR:
.PP
Allowing one of these tied filehandles to fall out of scope will \s-1NOT\s0 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.
.PP
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.
.SS "abort"
.IX Subsection "abort"
.Vb 1
\& $stream\->abort;
.Ve
.PP
Aborts the upload by deleting any chunks already uploaded to the database
and closing the stream.
.SS "close"
.IX Subsection "close"
.Vb 1
\& $file_doc = $stream\->close;
.Ve
.PP
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.
.PP
On success, the file document hash reference is returned as a convenience.
.PP
\&\fBImportant notes:\fR
.IP "\(bu" 4
Calling close will also cause any tied file handles created for the stream to also close.
.IP "\(bu" 4
\&\f(CW\*(C`close\*(C'\fR will be automatically called when a stream object is destroyed. When called this way, any errors thrown will not halt execution.
.IP "\(bu" 4
Calling \f(CW\*(C`close\*(C'\fR repeatedly will warn.
.SS "fileno"
.IX Subsection "fileno"
.Vb 1
\& if ( $stream\->fileno ) { ... }
.Ve
.PP
Works like the builtin \f(CW\*(C`fileno\*(C'\fR, but it returns \-1 if the stream is open
and undef if closed.
.SS "print"
.IX Subsection "print"
.Vb 1
\& $stream\->print(@data);
.Ve
.PP
Works like the builtin \f(CW\*(C`print\*(C'\fR.
.SS "printf"
.IX Subsection "printf"
.Vb 1
\& $stream\->printf($format, @data);
.Ve
.PP
Works like the builtin \f(CW\*(C`printf\*(C'\fR.
.SS "syswrite"
.IX Subsection "syswrite"
.Vb 3
\& $stream\->syswrite($buffer);
\& $stream\->syswrite($buffer, $length);
\& $stream\->syswrite($buffer, $length, $offset);
.Ve
.PP
Works like the builtin \f(CW\*(C`syswrite\*(C'\fR.
.SH "CAVEATS"
.IX Header "CAVEATS"
.SS "Character encodings"
.IX Subsection "Character encodings"
All the writer methods (e.g. \f(CW\*(C`print\*(C'\fR, \f(CW\*(C`printf\*(C'\fR, etc.) send a binary
representation of the string input provided (or generated in the case of
\&\f(CW\*(C`printf\*(C'\fR). Unless you explicitly encode it to bytes, this will be the
\&\fBinternal\fR representation of the string in the Perl interpreter. If you
have \s-1ASCII\s0 characters, it will already be bytes. If you have any
characters above \f(CW0xff\fR, it will be \s-1UTF\-8\s0 encoded codepoints. If you have
characters between \f(CW0x80\fR and \f(CW0xff\fR and not higher, you might have
either bytes or \s-1UTF\-8\s0 internally.
.PP
\&\fBYou are strongly encouraged to do your own character encoding with
the Encode module or equivalent and upload only bytes to GridFS\fR.
.SH "AUTHORS"
.IX Header "AUTHORS"
.IP "\(bu" 4
David Golden <david@mongodb.com>
.IP "\(bu" 4
Rassi <rassi@mongodb.com>
.IP "\(bu" 4
Mike Friedman <friedo@friedo.com>
.IP "\(bu" 4
Kristina Chodorow <k.chodorow@gmail.com>
.IP "\(bu" 4
Florian Ragwitz <rafl@debian.org>
.SH "COPYRIGHT AND LICENSE"
.IX Header "COPYRIGHT AND LICENSE"
This software is Copyright (c) 2018 by MongoDB, Inc.
.PP
This is free software, licensed under:
.PP
.Vb 1
\& The Apache License, Version 2.0, January 2004
.Ve
Mini Shell