API:EPrints/DataObj/File
EPrints 3 Reference: Directory Structure - Metadata Fields - Repository Configuration - XML Config Files - XML Export Format - EPrints data structure - Core API - Data Objects
Latest Source Code (3.4, 3.3) | Revision Log | Before editing this page please read Pod2Wiki
Contents
NAME
EPrints::DataObj::File - a stored file
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.
CORE FIELDS
fileid
Unique identifier for this file.
rev_number (int)
The number of the current revision of this file.
datasetid
Id of the dataset of the parent object.
objectid
Id of the parent object.
filename
Name of the file (may contain directory separators).
mime_type
MIME type of the file (e.g. "image/png").
hash
Check sum of the file.
hash_type
Name of check sum algorithm used (e.g. "MD5").
filesize
Size of the file in bytes.
mtime
Last modification time of the file.
url
Virtual field for storing the file's URL.
data
Virtual field for storing the file's content.
METHODS
Constructor Methods
new_from_filename
$dataobj = EPrints::DataObj::File->new_from_filename( $session, $dataobj, $filename )
Convenience method to get an existing File object for $filename stored in $dataobj.
Returns undef if no such record exists.
create_from_data
$dataobj = EPrints::DataObj::File->create_from_data( $session, $data [, $dataset ] )
Create a new File record using $data. If "_content" is defined in $data it will be read from and stored - for possible values see set_file().
Class Methods
get_system_field_info
$thing = EPrints::DataObj::File->get_system_field_info
Core fields.
get_dataset_id
$dataset = EPrints::DataObj::File->get_dataset_id
Returns the id of the EPrints::DataSet object to which this record belongs.
get_defaults
$defaults = EPrints::DataObj::File->get_defaults( $session, $data )
Return default values for this object based on the starting data.
Object Methods
clone
$new_file = $file->clone( $parent )
Clone the $file object (including contained files) and return the new object.
remove
$success = $file->remove
Delete the stored file.
get_local_copy
$filename = $file->get_local_copy()
Return the name of a local copy of the file (may be a File::Temp object).
Will retrieve and cache the remote object if necessary.
add_file
$success = $file->add_file( $filepath, $filename [, $preserve_path ] )
Read and store the contents of $filepath at $filename.
If $preserve_path is untrue will strip any leading path in $filename.
upload
$bytes = $file->upload( $filehandle, $filename, $filesize [, $preserve_path ] )
Read and store the data from $filehandle at $filename at the next revision number.
If $preserve_path is untrue will strip any leading path in $filename.
Returns the number of bytes read from $filehandle or undef on failure.
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.
write_copy_fh
$success = $stored->write_copy_fh( $filehandle )
Write a copy of this file to $filehandle.
generate_md5
$md5 = $stored->generate_md5
Calculates and returns the MD5 for this file.
generate_sha
$digest = $file->generate_sha( [ ALGORITHM ] )
Generate a SHA for this file, see Digest::SHA::PurePerl for a list of supported algorithms. Defaults to "256" (SHA-256).
Returns the hex-encoded digest.
add_plugin_copy
$stored->add_plugin_copy( $plugin, $sourceid )
Add a copy of this file stored using $plugin identified by $sourceid.
remove_plugin_copy
$stored->remove_plugin_copy( $plugin )
Remove the copy of this file stored using $plugin.
get_file
$success = $stored->get_file( CALLBACK [, $offset, $n ] )
Get the contents of the stored file - see EPrints::Storage/retrieve.
$offset is the position in bytes to start reading from, default 0.
$n is the number of bytes to read, default filesize.
set_file
$content_length = $stored->set_file( CONTENT, $content_length )
Reads data from CONTENT and stores it. Sets the MD5 hash and filesize.
If the write failed returns undef and sets the filesize to 0.
CONTENT may be one of:
CODEREF - will be called until it returns empty string ("")
SCALARREF - a scalar reference will be used as-is (expects bytes)
GLOB - will be treated as a file handle and read with sysread()
This method does not check the actual number of bytes read is the same as $content_length.
SEE ALSO
EPrints::DataObj and EPrints::DataSet.
