Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
MongoDB::GridFSBucket:UseroContributed PMongoDB::GridFSBucket::UploadStream(3)

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

VERSION
       version v1.8.0

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 MongoDB::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" repeately 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@mongodb.com>

       o   Rassi <rassi@mongodb.com>

       o   Mike	Friedman <friedo@friedo.com>

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

       o   Florian Ragwitz <rafl@debian.org>

COPYRIGHT AND LICENSE
       This software is	Copyright (c) 2017 by MongoDB, Inc.

       This is free software, licensed under:

	 The Apache License, Version 2.0, January 2004

perl v5.24.1			  2017-0MongoDB::GridFSBucket::UploadStream(3)

NAME | VERSION | SYNOPSIS | DESCRIPTION | ATTRIBUTES | METHODS | CAVEATS | AUTHORS | COPYRIGHT AND LICENSE

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=MongoDB::GridFSBucket::UploadStream&sektion=3&manpath=FreeBSD+12.1-RELEASE+and+Ports>

home | help