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
- 1 NAME
- 2 DESCRIPTION
- 3 CORE METADATA FIELDS
- 4 METHODS
- 4.1 Constructor Methods
- 4.2 Class Methods
- 4.3 Object Methods
- 4.3.1 clone
- 4.3.2 remove
- 4.3.3 update
- 4.3.4 get_local_copy
- 4.3.5 get_remote_copy
- 4.3.6 add_file
- 4.3.7 upload
- 4.3.8 write_copy
- 4.3.9 write_copy_fh
- 4.3.10 generate_md5
- 4.3.11 update_md5
- 4.3.12 generate_sha
- 4.3.13 update_sha
- 4.3.14 to_sax
- 4.3.15 add_plugin_copy
- 4.3.16 remove_plugin_copy
- 4.3.17 get_file
- 4.3.18 set_file
- 4.3.19 set_file_chunk
- 4.3.20 start_element
- 4.3.21 end_element
- 4.3.22 characters
- 4.3.23 render_filesize
- 4.3.24 get_url
- 4.3.25 path
- 5 SEE ALSO
- 6 COPYRIGHT
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 METADATA FIELDS
fileid (counter)
Unique identifier for this file.
datasetid (id)
Id of the dataset of the parent object.
objectid (int)
Id of the parent object.
filename (id)
Name of the file (may contain directory separators).
mime_type (id)
MIME type of the file (e.g. "image/png").
hash (id)
Check sum of the file.
hash_type (id)
Name of check sum algorithm used (e.g. "MD5").
filesize (bigint)
Size of the file in bytes.
mtime (timestamp)
Last modification time of the file.
url (url)
Virtual field for storing the file's URL.
data (base64)
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 return 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 )
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
Class Methods
get_system_field_info
$thing = EPrints::DataObj::File->get_system_field_info
Returns an array describing the system metadata of the document dataset.
get_dataset_id
$dataset = EPrints::DataObj::File->get_dataset_id
Returns the ID of the EPrints::DataSet object to which this record belongs.
Object Methods
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.
remove
$success = $file->remove
Delete the file data object and the file it stores.
Returns boolean depending on the success of removing this file.
update
$file->update( $epdata )
Updates the metadata for the file with $epdata.
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.
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.
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.
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.
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.
Returns boolean depending on success of writing copy of file to the file handle.
generate_md5
$md5 = $file->generate_md5
Calculates and returns the MD5 for this file.
update_md5
$md5 = $file->update_md5
Generates MD5 and sets hash and has_type (as MD5) for this file data object.
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.
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.
to_sax
$file->to_sax( %opts )
Generate SAX output for file data object and assign to Output of Handler specified in %opts.
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( $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.
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().
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.
start_element
$file->start_element( $data, $epdata, $state )
Consumes a SAX event. See <EPrints::DataObj#start_element> for more information.
end_element
$file->end_element( $data, $epdata, $state )
Ends element from start_element.
characters
$file->characters( $data, $epdata, $state )
Consumes characters within start_element.
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.
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.
path
$file->path
Returns the filesystem path for this file.
SEE ALSO
EPrints::DataObj and EPrints::DataSet.
COPYRIGHT
© Copyright 2000-2024 University of Southampton.
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/.
