Difference between revisions of "API:EPrints/DataObj/File"

Revision as of 17:06, 29 December 2021

EPrints 3 Reference: Directory Structure - Metadata Fields - Repository Configuration - XML Config Files - XML Export Format - EPrints data structure - Core API - Data Objects

API: Core API

Latest Source Code (3.4, 3.3) | Revision Log | Before editing this page please read Pod2Wiki

NAME

EPrints::DataObj::File - a stored file

User Comments

DESCRIPTION

This class contains the technical metadata associated with a file. A file is a sequence of bytes stored in the storage layer (a "stored object"). Utility methods for storing and retrieving the stored object from the storage layer are made available.

Revision numbers on File work slightly differently to other objects. A File is only revised when it's stored object is changed and not when changes to it's metadata are made.

This class is a subclass of EPrints::DataObj::SubObject.

User Comments

CORE METADATA FIELDS

User Comments

fileid (counter)

Unique identifier for this file.

User Comments

datasetid (id)

Id of the dataset of the parent object.

User Comments

objectid (int)

Id of the parent object.

User Comments

filename (id)

Name of the file (may contain directory separators).

User Comments

mime_type (id)

MIME type of the file (e.g. "image/png").

User Comments

hash (id)

Check sum of the file.

User Comments

hash_type (id)

Name of check sum algorithm used (e.g. "MD5").

User Comments

filesize (bigint)

Size of the file in bytes.

User Comments

mtime (timestamp)

Last modification time of the file.

User Comments

url (url)

Virtual field for storing the file's URL.

User Comments

data (base64)

Virtual field for storing the file's content.

User Comments

METHODS

User Comments

Constructor Methods

User Comments

new_from_filename

$dataobj = EPrints::DataObj::File->new_from_filename( $session, $dataobj, $filename )

Convenience method to return an existing file object for $filename stored in $dataobj.

Returns undef if no such record exists.

User Comments

create_from_data

$dataobj = EPrints::DataObj::File->create_from_data( $session, $data, $dataset )

Returns a new file record using $data and the file $dataset.

Private data elements:

_content - content to pass to set_file.
_filepath - path to source file used for improved mime-type detection

User Comments

Class Methods

User Comments

get_system_field_info

$thing = EPrints::DataObj::File->get_system_field_info

Returns an array describing the system metadata of the document dataset.

User Comments

get_dataset_id

$dataset = EPrints::DataObj::File->get_dataset_id

Returns the ID of the EPrints::DataSet object to which this record belongs.

User Comments

Object Methods

User Comments

clone

$new_file = $file->clone( $parent )

Clone the file object (including contained files) and return the new object. Uses $parent to set the objectid of the cloned file data object, in case this needs to be different to the original.

User Comments

remove

$success = $file->remove

Delete the file data object and the file it stores.

Returns boolean depending on the success of removing this file.

User Comments

update

$file->update( $epdata )

Updates the metadata for the file with $epdata.

User Comments

get_local_copy

$filename = $file->get_local_copy

Returns the name of a local copy of the file (may be a File::Temp object).

Uses EPrints::Storage#get_local_copy which in turn calls the configured local storage plugin.

User Comments

get_remote_copy

$filename = $file->get_remote_copy

Returns the name of a remote copy of the file (may be a File::Temp object).

Uses EPrints::Storage#get_local_copy which in turn calls the configured remote storage plugin.

User Comments

add_file

$success = $file->add_file( $filepath, $filename [, $preserve_path ] )

Reads and stores the contents of $filepath at $filename.

If $preserve_path is not true will strip any leading path in $filename.

Returns a boolean depending on the success of adding the file.

User Comments

upload

$bytes = $file->upload( $filehandle, $filename, $filesize [, $preserve_path ] )

Reads and stores the data from $filehandle at $filename at the next revision number.

If $preserve_path is not true will strip any leading path in $filename.

Returns the number of bytes read from $filehandle or undef on failure.

User Comments

write_copy

$success = $stored->write_copy( $filename )

Write a copy of this file to $filename.

Returns true if the written file contains the same number of bytes as the stored file.

User Comments

write_copy_fh

$success = $stored->write_copy_fh( $filehandle )

Write a copy of this file to $filehandle.

Returns boolean depending on success of writing copy of file to the file handle.

User Comments

generate_md5

$md5 = $file->generate_md5

Calculates and returns the MD5 for this file.

User Comments

update_md5

$md5 = $file->update_md5

Generates MD5 and sets hash and has_type (as MD5) for this file data object.

User Comments

generate_sha

$digest = $file->generate_sha( [ $alg ] )

Generates a SHA for this file, see Digest::SHA for a list of supported algorithms. Defaults to 256 (SHA-256) if $alg is not set.

Returns the hex-encoded digest.

User Comments

update_sha

$md5 = $file->update_sha

Generates a SHA for this file, see Digest::SHA for a list of supported algorithms. Defaults to 256 (SHA-256) if $alg is not set. Then sets the hash and c<has_type> for this file data object.

User Comments

to_sax

$file->to_sax( %opts )

Generate SAX output for file data object and assign to Output of Handler specified in %opts.

User Comments

add_plugin_copy

$stored->add_plugin_copy( $plugin, $sourceid )

Add a copy of this file stored using $plugin identified by $sourceid.

User Comments

remove_plugin_copy

$stored->remove_plugin_copy( $plugin )

Remove the copy of this file stored using $plugin.

User Comments

get_file

$success = $stored->get_file( $f, [ $offset, $n ] )

Get the contents of the stored file.

$offset is the position in bytes to start reading from, defaults to 0.

$n is the number of bytes to read, defaults to filesize.

$f is:

 sub {
   my( $buffer ) = @_;
   ...
   return 1;
 }

Returns boolean dependent on whether file was successfully retrieved.

User Comments

set_file

$content_length = $file->set_file( $content, $clen )

Write $clen bytes from $content to the file object. Updates filesize and hash. You must then call commit) to save these changes.

Returns an integer for the content length or undef on failure.

$content may be one of:

CODEREF - Will be called until it returns empty string ("").
SCALARREF - A scalar reference to a string of octets that will be written as-is.
GLOB - Will be treated as a file handle and read with sysread().

User Comments

set_file_chunk

$content_length = $file->set_file_chunk( $content, $clen, $offset, $total )

Write a chunk of data to the content, overwriting or appending to the existing content. See set_file for $content and $clen. filesize is updated if $offset + $content_length is greater than the current filesize.

$offset is the starting point (in bytes) to write. $total is the total size of the file, used to determine where to store the content.

Returns the number of bytes written or undef on failure.

User Comments

start_element

$file->start_element( $data, $epdata, $state )

Consumes a SAX event. See <EPrints::DataObj#start_element> for more information.

User Comments

end_element

$file->end_element( $data, $epdata, $state )

Ends element from start_element.

User Comments

characters

$file->characters( $data, $epdata, $state )

Consumes characters within start_element.

User Comments

render_filesize

EPrints::DataObj::File->render_filesize( $repo, $field, $value )

Returns an XHTML DOM fragment, which is either empty if $value is not set or a human-readable rendering of this file size.

User Comments

get_url

$file->get_url

Returns the URL from which this file can be downloaded.

Calls EPrints::DataObj::Document#get_url on the parent object for this file with the filename as a parameter.

User Comments

path

$file->path

Returns the filesystem path for this file.

User Comments

COPYRIGHT

EPrints 3.4 is supplied by EPrints Services.

http://www.eprints.org/eprints-3.4/

LICENSE

This file is part of EPrints 3.4 http://www.eprints.org/.

EPrints 3.4 and this file are released under the terms of the GNU Lesser General Public License version 3 as published by the Free Software Foundation unless otherwise stated.

EPrints 3.4 is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.

You should have received a copy of the GNU Lesser General Public License along with EPrints 3.4. If not, see http://www.gnu.org/licenses/.

User Comments

@@ Line 1: / Line 1: @@
 <!-- Pod2Wiki=_preamble_
-This page has been automatically generated from the EPrints 3.2 source. Any wiki changes made between the 'Pod2Wiki=*' and 'Edit below this comment' comments will be lost.
+This page has been automatically generated from the EPrints 3.4 source. Any wiki changes made between the 'Pod2Wiki=*' and 'Edit below this comment' comments will be lost.
-  -->{{API}}{{Pod2Wiki}}{{API:Source|file=perl_lib/EPrints/DataObj/File.pm|package_name=EPrints::DataObj::File}}[[Category:API|FILE]][[Category:API:EPrints/DataObj|FILE]][[Category:API:EPrints/DataObj/File|FILE]]<div><!-- Edit below this comment -->
+  -->{{API}}{{Pod2Wiki}}{{API:Source|file=EPrints/DataObj/File.pm|package_name=EPrints::DataObj::File}}[[Category:API|FILE]][[Category:API:EPrints/DataObj|FILE]]<div><!-- Edit below this comment -->
 <!-- Pod2Wiki=_private_ --><!-- Pod2Wiki=head_name -->
 ==NAME==
-EPrints::DataObj::File - a stored file
+'''EPrints::DataObj::File''' - a stored file
+<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
+<span style='display:none'>User Comments</span>
 <!-- Edit below this comment -->
 <!-- Pod2Wiki= -->
+</div>
 <!-- Pod2Wiki=head_description -->
 ==DESCRIPTION==
-This class contains the technical metadata associated with a file. A file is a sequence of bytes stored in the storage layer (a "stored object"). Utility methods for storing and retrieving the stored object from the storage layer are made available.
+This class contains the technical metadata associated with a file. A  file is a sequence of bytes stored in the storage layer (a "stored  object"). Utility methods for storing and retrieving the stored object  from the storage layer are made available.
-Revision numbers on File work slightly differently to other objects. A File is only revised when it's stored object is changed and not when changes to it's metadata are made.
+Revision numbers on File work slightly differently to other objects.  A File is only revised when it's stored object is changed and not when  changes to it's metadata are made.
 This class is a subclass of [[API:EPrints/DataObj/SubObject|EPrints::DataObj::SubObject]].
+<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
+<span style='display:none'>User Comments</span>
 <!-- Edit below this comment -->
 <!-- Pod2Wiki= -->
-<!-- Pod2Wiki=head_core_fields -->
+</div>
-==CORE FIELDS==
+<!-- Pod2Wiki=head_core_metadata_fields -->
-* fileid
+==CORE METADATA FIELDS==
-: Unique identifier for this file.
+<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
+<span style='display:none'>User Comments</span>
+<!-- Edit below this comment -->
+<!-- Pod2Wiki= -->
+</div>
+<!-- Pod2Wiki=item_fileid -->
+===fileid (counter)===
+Unique identifier for this file.
+<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
+<span style='display:none'>User Comments</span>
+<!-- Edit below this comment -->
+<!-- Pod2Wiki= -->
+</div>
+<!-- Pod2Wiki=item_datasetid -->
+===datasetid (id)===
+Id of the dataset of the parent object.
+<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
+<span style='display:none'>User Comments</span>
+<!-- Edit below this comment -->
+<!-- Pod2Wiki= -->
+</div>
+<!-- Pod2Wiki=item_objectid -->
+===objectid (int)===
+Id of the parent object.
+<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
+<span style='display:none'>User Comments</span>
+<!-- Edit below this comment -->
+<!-- Pod2Wiki= -->
+</div>
+<!-- Pod2Wiki=item_filename -->
+===filename (id)===
+Name of the file (may contain directory separators).
+<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
+<span style='display:none'>User Comments</span>
+<!-- Edit below this comment -->
+<!-- Pod2Wiki= -->
+</div>
+<!-- Pod2Wiki=item_mime_type -->
+===mime_type (id)===
+MIME type of the file (e.g. "image/png").
+<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
+<span style='display:none'>User Comments</span>
+<!-- Edit below this comment -->
+<!-- Pod2Wiki= -->
+</div>
+<!-- Pod2Wiki=item_hash -->
+===hash (id)===
+Check sum of the file.
+<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
+<span style='display:none'>User Comments</span>
+<!-- Edit below this comment -->
+<!-- Pod2Wiki= -->
+</div>
+<!-- Pod2Wiki=item_hash_type -->
+===hash_type (id)===
+Name of check sum algorithm used (e.g. "MD5").
+<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
+<span style='display:none'>User Comments</span>
+<!-- Edit below this comment -->
+<!-- Pod2Wiki= -->
+</div>
+<!-- Pod2Wiki=item_filesize -->
+===filesize (bigint)===
+Size of the file in bytes.
-* rev_number (int)
+<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
-: The number of the current revision of this file.
+<span style='display:none'>User Comments</span>
+<!-- Edit below this comment -->
-* datasetid
-: Id of the dataset of the parent object.
-* objectid
+<!-- Pod2Wiki= -->
-: Id of the parent object.
+</div>
+<!-- Pod2Wiki=item_mtime -->
+===mtime (timestamp)===
-* filename
+Last modification time of the file.
-: Name of the file (may contain directory separators).
-* mime_type
+<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
-: MIME type of the file (e.g. "image/png").
+<span style='display:none'>User Comments</span>
+<!-- Edit below this comment -->
-* hash
-: Check sum of the file.
-* hash_type
+<!-- Pod2Wiki= -->
-: Name of check sum algorithm used (e.g. "MD5").
+</div>
+<!-- Pod2Wiki=item_url -->
+===url (url)===
-* filesize
+Virtual field for storing the file's URL.
-: Size of the file in bytes.
-* mtime
+<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
-: Last modification time of the file.
+<span style='display:none'>User Comments</span>
+<!-- Edit below this comment -->
-* url
-: Virtual field for storing the file's URL.
-* data
+<!-- Pod2Wiki= -->
-: Virtual field for storing the file's content.
+</div>
+<!-- Pod2Wiki=item_data -->
+===data (base64)===
+Virtual field for storing the file's content.
+<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
+<span style='display:none'>User Comments</span>
 <!-- Edit below this comment -->
 <!-- Pod2Wiki= -->
+</div>
 <!-- Pod2Wiki=head_methods -->
 ==METHODS==
+<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
+<span style='display:none'>User Comments</span>
+<!-- Edit below this comment -->
+<!-- Pod2Wiki= -->
+</div>
 <!-- Pod2Wiki=head_constructor_methods -->
 ===Constructor Methods===
+<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
+<span style='display:none'>User Comments</span>
 <!-- Edit below this comment -->
 <!-- Pod2Wiki= -->
-<!-- Pod2Wiki=head_new_from_filename -->
+</div>
-===new_from_filename===
+<!-- Pod2Wiki=item_new_from_filename -->
+====new_from_filename====
-<source lang="perl">$dataobj = EPrints::DataObj::File->new_from_filename( $session, $dataobj, $filename )
+ $dataobj = EPrints::DataObj::File-&gt;new_from_filename( $session, $dataobj, $filename )
+Convenience method to return an existing file object for <tt>$filename</tt>  stored in <tt>$dataobj</tt>.
-</source>
+Returns <tt>undef</tt> if no such record exists.
-Convenience method to get an existing File object for $filename stored in $dataobj.
-Returns undef if no such record exists.
+<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
+<span style='display:none'>User Comments</span>
 <!-- Edit below this comment -->
 <!-- Pod2Wiki= -->
-<!-- Pod2Wiki=head_create_from_data -->
+</div>
-===create_from_data===
+<!-- Pod2Wiki=item_create_from_data -->
+====create_from_data====
-<source lang="perl">$dataobj = EPrints::DataObj::File->create_from_data( $session, $data [, $dataset ] )
+ $dataobj = EPrints::DataObj::File-&gt;create_from_data( $session, $data, $dataset )
+Returns a new file record using <tt>$data</tt> and the file <tt>$dataset</tt>.
-</source>
-Create a new File record using $data.
 Private data elements:
-<pre>  _content - content to pass to [[API:EPrints/DataObj/File#set_file|set_file]].
+  _content - content to pass to [[API:EPrints/DataObj/File#set_file|set_file]].
-  _filepath - path to source file used for improved mime-type detection</pre>
+ _filepath - path to source file used for improved mime-type detection
+<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
+<span style='display:none'>User Comments</span>
 <!-- Edit below this comment -->
 <!-- Pod2Wiki= -->
+</div>
 <!-- Pod2Wiki=head_class_methods -->
 ===Class Methods===
+<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
+<span style='display:none'>User Comments</span>
 <!-- Edit below this comment -->
 <!-- Pod2Wiki= -->
-<!-- Pod2Wiki=head_get_system_field_info -->
+</div>
-===get_system_field_info===
+<!-- Pod2Wiki=item_get_system_field_info -->
+====get_system_field_info====
-<source lang="perl">$thing = EPrints::DataObj::File->get_system_field_info
-</source>
+ $thing = EPrints::DataObj::File-&gt;get_system_field_info
-Core fields.
+Returns an array describing the system metadata of the document dataset.
+<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
+<span style='display:none'>User Comments</span>
 <!-- Edit below this comment -->
 <!-- Pod2Wiki= -->
-<!-- Pod2Wiki=head_get_dataset_id -->
+</div>
-===get_dataset_id===
+<!-- Pod2Wiki=item_get_dataset_id -->
+====get_dataset_id====
-<source lang="perl">$dataset = EPrints::DataObj::File->get_dataset_id
-</source>
+ $dataset = EPrints::DataObj::File-&gt;get_dataset_id
-Returns the id of the [[API:EPrints/DataSet|EPrints::DataSet]] object to which this record belongs.
+Returns the ID  of the [[API:EPrints/DataSet|EPrints::DataSet]] object to which this record  belongs.
+<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
+<span style='display:none'>User Comments</span>
 <!-- Edit below this comment -->
 <!-- Pod2Wiki= -->
+</div>
 <!-- Pod2Wiki=head_object_methods -->
 ===Object Methods===
+<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
+<span style='display:none'>User Comments</span>
 <!-- Edit below this comment -->
 <!-- Pod2Wiki= -->
-<!-- Pod2Wiki=head_clone -->
+</div>
-===clone===
+<!-- Pod2Wiki=item_clone -->
+====clone====
-<source lang="perl">$new_file = $file->clone( $parent )
-</source>
+ $new_file = $file-&gt;clone( $parent )
-Clone the $file object (including contained files) and return the new object.
+Clone the file object (including contained files) and return the new  object. Uses <tt>$parent</tt> to set the <tt>objectid</tt> of the cloned file data object, in case this needs to be different to the original.
+<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
+<span style='display:none'>User Comments</span>
 <!-- Edit below this comment -->
 <!-- Pod2Wiki= -->
-<!-- Pod2Wiki=head_remove -->
+</div>
-===remove===
+<!-- Pod2Wiki=item_remove -->
+====remove====
-<source lang="perl">$success = $file->remove
+ $success = $file-&gt;remove
+Delete the file data object and the file it stores.
-</source>
+Returns boolean depending on the success of removing this file.
-Delete the stored file.
+<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
+<span style='display:none'>User Comments</span>
 <!-- Edit below this comment -->
 <!-- Pod2Wiki= -->
-<!-- Pod2Wiki=head_update -->
+</div>
-===update===
+<!-- Pod2Wiki=item_update -->
+====update====
-<source lang="perl">$file->update( $epdata )
+ $file-&gt;update( $epdata )
+Updates the metadata for the file with <tt>$epdata</tt>.
-</source>
+<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
+<span style='display:none'>User Comments</span>
 <!-- Edit below this comment -->
 <!-- Pod2Wiki= -->
-<!-- Pod2Wiki=head_get_local_copy -->
+</div>
-===get_local_copy===
+<!-- Pod2Wiki=item_get_local_copy -->
+====get_local_copy====
+ $filename = $file-&gt;get_local_copy
+Returns the name of a local copy of the file (may be a {{API:PodLink|file=File/Temp|package_name=File::Temp|section=|text=File::Temp}}  object).
+Uses [[API:EPrints/Storage#get_local_copy|EPrints::Storage#get_local_copy]] which in turn calls the  configured local storage plugin.
-<source lang="perl">$filename = $file->get_local_copy()
+<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
+<span style='display:none'>User Comments</span>
+<!-- Edit below this comment -->
-</source>
-Return the name of a local copy of the file (may be a {{API:PodLink|file=File/Temp|package_name=File::Temp|section=|text=File::Temp}} object).
-Will retrieve and cache the remote object if necessary.
+<!-- Pod2Wiki= -->
+</div>
+<!-- Pod2Wiki=item_get_remote_copy -->
+====get_remote_copy====
+ $filename = $file-&gt;get_remote_copy
+Returns the name of a remote copy of the file (may be a {{API:PodLink|file=File/Temp|package_name=File::Temp|section=|text=File::Temp}} object).
+Uses [[API:EPrints/Storage#get_local_copy|EPrints::Storage#get_local_copy]] which in turn calls the configured remote storage plugin.
+<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
+<span style='display:none'>User Comments</span>
 <!-- Edit below this comment -->
 <!-- Pod2Wiki= -->
-<!-- Pod2Wiki=head_add_file -->
+</div>
-===add_file===
+<!-- Pod2Wiki=item_add_file -->
+====add_file====
-<source lang="perl">$success = $file->add_file( $filepath, $filename [, $preserve_path ] )
+ $success = $file-&gt;add_file( $filepath, $filename [, $preserve_path ] )
+Reads and stores the contents of <tt>$filepath</tt> at <tt>$filename</tt>.
-</source>
+If <tt>$preserve_path</tt> is not <tt>true</tt> will strip any leading path in  <tt>$filename</tt>.
-Read and store the contents of $filepath at $filename.
-If $preserve_path is untrue will strip any leading path in $filename.
+Returns a boolean depending on the success of adding the file.
+<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
+<span style='display:none'>User Comments</span>
 <!-- Edit below this comment -->
 <!-- Pod2Wiki= -->
-<!-- Pod2Wiki=head_upload -->
+</div>
-===upload===
+<!-- Pod2Wiki=item_upload -->
+====upload====
-<source lang="perl">$bytes = $file->upload( $filehandle, $filename, $filesize [, $preserve_path ] )
-</source>
+ $bytes = $file-&gt;upload( $filehandle, $filename, $filesize [, $preserve_path ] )
-Read and store the data from $filehandle at $filename at the next revision number.
+Reads and stores the data from <tt>$filehandle</tt> at <tt>$filename</tt> at the  next revision number.
-If $preserve_path is untrue will strip any leading path in $filename.
+If <tt>$preserve_path</tt> is not <tt>true</tt> will strip any leading path in  <tt>$filename</tt>.
 Returns the number of bytes read from $filehandle or undef on failure.
+<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
+<span style='display:none'>User Comments</span>
 <!-- Edit below this comment -->
 <!-- Pod2Wiki= -->
-<!-- Pod2Wiki=head_write_copy -->
+</div>
-===write_copy===
+<!-- Pod2Wiki=item_write_copy -->
+====write_copy====
-<source lang="perl">$success = $stored->write_copy( $filename )
+ $success = $stored-&gt;write_copy( $filename )
+Write a copy of this file to <tt>$filename</tt>.
-</source>
+Returns <tt>true</tt> if the written file contains the same number of bytes  as the stored file.
-Write a copy of this file to $filename.
-Returns true if the written file contains the same number of bytes as the stored file.
+<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
+<span style='display:none'>User Comments</span>
 <!-- Edit below this comment -->
 <!-- Pod2Wiki= -->
-<!-- Pod2Wiki=head_write_copy_fh -->
+</div>
-===write_copy_fh===
+<!-- Pod2Wiki=item_write_copy_fh -->
+====write_copy_fh====
-<source lang="perl">$success = $stored->write_copy_fh( $filehandle )
+ $success = $stored-&gt;write_copy_fh( $filehandle )
+Write a copy of this file to <tt>$filehandle</tt>.
-</source>
+Returns boolean depending on success of writing copy of file to the file handle.
-Write a copy of this file to $filehandle.
+<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
+<span style='display:none'>User Comments</span>
 <!-- Edit below this comment -->
 <!-- Pod2Wiki= -->
-<!-- Pod2Wiki=head_generate_md5 -->
+</div>
-===generate_md5===
+<!-- Pod2Wiki=item_generate_md5 -->
+====generate_md5====
-<source lang="perl">$md5 = $stored->generate_md5
+ $md5 = $file-&gt;generate_md5
-</source>
 Calculates and returns the MD5 for this file.
+<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
+<span style='display:none'>User Comments</span>
 <!-- Edit below this comment -->
 <!-- Pod2Wiki= -->
-<!-- Pod2Wiki=head_generate_sha -->
+</div>
-===generate_sha===
+<!-- Pod2Wiki=item_update_md5 -->
+====update_md5====
+ $md5 = $file-&gt;update_md5
+Generates MD5 and sets <tt>hash</tt> and <tt>has_type</tt> (as <tt>MD5</tt>) for this  file data object.
+<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
+<span style='display:none'>User Comments</span>
+<!-- Edit below this comment -->
-<source lang="perl">$digest = $file->generate_sha( [ ALGORITHM ] )
+<!-- Pod2Wiki= -->
+</div>
+<!-- Pod2Wiki=item_generate_sha -->
+====generate_sha====
-</source>
+ $digest = $file-&gt;generate_sha( [ $alg ] )
-Generate a SHA for this file, see {{API:PodLink|file=Digest/SHA|package_name=Digest::SHA|section=|text=Digest::SHA}} for a list of supported algorithms. Defaults to "256" (SHA-256).
+Generates a SHA for this file, see {{API:PodLink|file=Digest/SHA|package_name=Digest::SHA|section=|text=Digest::SHA}} for a list of  supported algorithms. Defaults to <tt>256</tt> (SHA-256) if <tt>$alg</tt> is not set.
 Returns the hex-encoded digest.
+<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
+<span style='display:none'>User Comments</span>
 <!-- Edit below this comment -->
 <!-- Pod2Wiki= -->
-<!-- Pod2Wiki=head_add_plugin_copy -->
+</div>
-===add_plugin_copy===
+<!-- Pod2Wiki=item_update_sha -->
+====update_sha====
+ $md5 = $file-&gt;update_sha
+Generates a SHA for this file, see {{API:PodLink|file=Digest/SHA|package_name=Digest::SHA|section=|text=Digest::SHA}} for a list of supported algorithms. Defaults to <tt>256</tt> (SHA-256) if <tt>$alg</tt> is not set. Then sets the <tt>hash</tt> and c&lt;has_type&gt; for this file data object.
+<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
+<span style='display:none'>User Comments</span>
+<!-- Edit below this comment -->
-<source lang="perl">$stored->add_plugin_copy( $plugin, $sourceid )
+<!-- Pod2Wiki= -->
+</div>
+<!-- Pod2Wiki=item_to_sax -->
+====to_sax====
-</source>
+ $file-&gt;to_sax( %opts )
-Add a copy of this file stored using $plugin identified by $sourceid.
+Generate SAX output for file data object and assign to <tt>Output</tt> of <tt>Handler</tt> specified in <tt>%opts</tt>.
+<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
+<span style='display:none'>User Comments</span>
 <!-- Edit below this comment -->
 <!-- Pod2Wiki= -->
-<!-- Pod2Wiki=head_remove_plugin_copy -->
+</div>
-===remove_plugin_copy===
+<!-- Pod2Wiki=item_add_plugin_copy -->
+====add_plugin_copy====
-<source lang="perl">$stored->remove_plugin_copy( $plugin )
+ $stored-&gt;add_plugin_copy( $plugin, $sourceid )
+Add a copy of this file stored using <tt>$plugin</tt> identified by  <tt>$sourceid</tt>.
-</source>
+<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
-Remove the copy of this file stored using $plugin.
+<span style='display:none'>User Comments</span>
+<!-- Edit below this comment -->
+<!-- Pod2Wiki= -->
+</div>
+<!-- Pod2Wiki=item_remove_plugin_copy -->
+====remove_plugin_copy====
+ $stored-&gt;remove_plugin_copy( $plugin )
+Remove the copy of this file stored using <tt>$plugin</tt>.
+<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
+<span style='display:none'>User Comments</span>
 <!-- Edit below this comment -->
 <!-- Pod2Wiki= -->
-<!-- Pod2Wiki=head_get_file -->
+</div>
-===get_file===
+<!-- Pod2Wiki=item_get_file -->
+====get_file====
-<source lang="perl">$success = $stored->get_file( CALLBACK [, $offset, $n ] )
+ $success = $stored-&gt;get_file( $f, [ $offset, $n ] )
+Get the contents of the stored file.
-</source>
+<tt>$offset</tt> is the position in bytes to start reading from, defaults to  0.
-Get the contents of the stored file.
+<tt>$n</tt> is the number of bytes to read, defaults to <tt>filesize</tt>.
+<tt>$f</tt> is:
-$offset is the position in bytes to start reading from, defaults to 0.
+  sub {
+    my( $buffer ) = @_;
+    ...
+    return 1;
+  }
+Returns boolean dependent on whether file was successfully retrieved.
-$n is the number of bytes to read, defaults to <code>filesize</code>.
+<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
+<span style='display:none'>User Comments</span>
+<!-- Edit below this comment -->
-CALLBACK is:
-<source lang="perl">sub {
+<!-- Pod2Wiki= -->
-	my( $buffer ) = @_;
+</div>
+<!-- Pod2Wiki=item_set_file -->
+====set_file====
-	print $buffer;
+ $content_length = $file-&gt;set_file( $content, $clen )
+Write <tt>$clen</tt> bytes from <tt>$content</tt> to the file object. Updates  <tt>filesize</tt> and <tt>hash</tt>. You must then call [[API:EPrints/DataObj/File#commit|commit]]) to save these  changes.
-	return 1;
+Returns an integer for the content length or <tt>undef</tt> on failure.
-}</source>
-Returning 0 from the callback will cause the read to abort.
+<tt>$content</tt> may be one of:
+ CODEREF - Will be called until it returns empty string ("").
+ SCALARREF - A scalar reference to a string of octets that will be written as-is.
+ GLOB - Will be treated as a file handle and read with sysread().
+<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
+<span style='display:none'>User Comments</span>
 <!-- Edit below this comment -->
 <!-- Pod2Wiki= -->
-<!-- Pod2Wiki=head_set_file -->
+</div>
-===set_file===
+<!-- Pod2Wiki=item_set_file_chunk -->
+====set_file_chunk====
-<source lang="perl">$content_length = $stored->set_file( CONTENT, $content_length )
+ $content_length = $file-&gt;set_file_chunk( $content, $clen, $offset, $total )
+Write a chunk of data to the content, overwriting or appending to the  existing content. See [[API:EPrints/DataObj/File#set_file|set_file]] for <tt>$content</tt> and <tt>$clen</tt>.  <tt>filesize</tt> is updated if <tt>$offset + $content_length</tt> is greater than  the current <tt>filesize</tt>.
-</source>
+<tt>$offset</tt> is the starting point (in bytes) to write. <tt>$total</tt> is the  total size of the file, used to determine where to store the content.
-Write $content_length bytes from CONTENT to the file object. Updates <code>filesize</code> and <code>hash</code> (you must call [[API:EPrints/DataObj/File#commit|commit]]).
-Returns $content_length or undef on failure.
+Returns the number of bytes written or <tt>undef</tt> on failure.
-If CONTENT has fewer bytes than $content_length the result is undetermined and a warning will be printed.
+<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
+<span style='display:none'>User Comments</span>
+<!-- Edit below this comment -->
-CONTENT may be any one of:
-* CODEREF
+<!-- Pod2Wiki= -->
-: Will be called until it returns empty string ("").
+</div>
+<!-- Pod2Wiki=item_start_element -->
+====start_element====
-<source lang="perl">sub {
+ $file-&gt;start_element( $data, $epdata, $state )
-	sysread($fh, my $buffer, 1024);
+Consumes a SAX event.  See &lt;EPrints::DataObj#start_element&gt; for more information.
-	return $buffer;
-};</source>
-* SCALARREF
+<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
-: A scalar reference to a string of octets that will be written as-is.
+<span style='display:none'>User Comments</span>
+<!-- Edit below this comment -->
-* GLOB
-: Will be treated as a file handle and read with sysread() until the eof.
+<!-- Pod2Wiki= -->
+</div>
+<!-- Pod2Wiki=item_end_element -->
+====end_element====
+ $file-&gt;end_element( $data, $epdata, $state )
+Ends element from [[API:EPrints/DataObj/File#start_element|start_element]].
+<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
+<span style='display:none'>User Comments</span>
 <!-- Edit below this comment -->
 <!-- Pod2Wiki= -->
-<!-- Pod2Wiki=head_set_file_chunk -->
+</div>
-===set_file_chunk===
+<!-- Pod2Wiki=item_characters -->
+====characters====
-<source lang="perl">$content_length = $file->set_file_chunk( CONTENT, $content_length, $offset, $total )
+ $file-&gt;characters( $data, $epdata, $state )
+Consumes characters within [[API:EPrints/DataObj/File#start_element|start_element]].
-</source>
+<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
-Write a chunk of data to the content, overwriting or appending to the existing content. See [[API:EPrints/DataObj/File#set_file|set_file]] for CONTENT and $content_length. <code>filesize</code> is updated if $offset + $content_length is greater than the current <code>filesize</code>.
+<span style='display:none'>User Comments</span>
+<!-- Edit below this comment -->
-$offset is the starting point (in bytes) to write. $total is the total file size, used to determine where to store the content.
-Returns the number of bytes written or undef on failure.
+<!-- Pod2Wiki= -->
+</div>
+<!-- Pod2Wiki=item_render_filesize -->
+====render_filesize====
+ EPrints::DataObj::File-&gt;render_filesize( $repo, $field, $value )
+Returns an XHTML DOM fragment, which is either empty if <tt>$value</tt> is not set or a human-readable rendering of this file size.
+<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
+<span style='display:none'>User Comments</span>
 <!-- Edit below this comment -->
 <!-- Pod2Wiki= -->
-<!-- Pod2Wiki=head_see_also -->
+</div>
-==SEE ALSO==
+<!-- Pod2Wiki=item_get_url -->
-[[API:EPrints/Storage|EPrints::Storage]]
+====get_url====
+ $file-&gt;get_url
+Returns the URL from which this file can be downloaded.
-[[API:EPrints/DataObj|EPrints::DataObj]] and [[API:EPrints/DataSet|EPrints::DataSet]].
+Calls [[API:EPrints/DataObj/Document#get_url|EPrints::DataObj::Document#get_url]] on the parent object for this file with the <tt>filename</tt> as a parameter.
+<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
+<span style='display:none'>User Comments</span>
 <!-- Edit below this comment -->
 <!-- Pod2Wiki= -->
-<!-- Pod2Wiki=head_copyright -->
+</div>
-==COPYRIGHT==
+<!-- Pod2Wiki=item_path -->
-Copyright 2000-2013 University of Southampton.
+====path====
-This file is part of EPrints http://www.eprints.org/.
+ $file-&gt;path
+Returns the filesystem path for this file.
-EPrints is free software: you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.
+<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
+<span style='display:none'>User Comments</span>
+<!-- Edit below this comment -->
-EPrints is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU Lesser General Public License for more details.
-You should have received a copy of the GNU Lesser General Public License along with EPrints.  If not, see http://www.gnu.org/licenses/.
+<!-- Pod2Wiki= -->
+</div>
+<!-- Pod2Wiki=head_see_also -->
+==SEE ALSO==
+[[API:EPrints/DataObj|EPrints::DataObj]] and [[API:EPrints/DataSet|EPrints::DataSet]].
+<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
+<span style='display:none'>User Comments</span>
 <!-- Edit below this comment -->
 <!-- Pod2Wiki= -->
-<!-- Pod2Wiki=_postamble_ -->
+</div>
+<!-- Pod2Wiki=head_copyright -->
+==COPYRIGHT==
+{{API:Copyright}}
+<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
+<span style='display:none'>User Comments</span>
 <!-- Edit below this comment -->
+<!-- Pod2Wiki= -->
+</div>
+<!-- Pod2Wiki=_postamble_ --><!-- Edit below this comment -->

Difference between revisions of "API:EPrints/DataObj/File"

Revision as of 17:06, 29 December 2021

Contents

NAME

DESCRIPTION

CORE METADATA FIELDS

fileid (counter)

datasetid (id)

objectid (int)

filename (id)

mime_type (id)

hash (id)

hash_type (id)

filesize (bigint)

mtime (timestamp)

url (url)

data (base64)

METHODS

Constructor Methods

new_from_filename

create_from_data

Class Methods

get_system_field_info

get_dataset_id

Object Methods

clone

remove

update

get_local_copy

get_remote_copy

add_file

upload

write_copy

write_copy_fh

generate_md5

update_md5

generate_sha

update_sha

to_sax

add_plugin_copy

remove_plugin_copy

get_file

set_file

set_file_chunk

start_element

end_element

characters

render_filesize

get_url

path

SEE ALSO

COPYRIGHT

LICENSE

Navigation menu

Search