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

From EPrints Documentation
Jump to: navigation, search
Line 234: Line 234:
 
====get_system_field_info====
 
====get_system_field_info====
  
  $thing = EPrints::DataObj::File->get_system_field_info
+
  $fields = EPrints::DataObj::File->get_system_field_info
 
Returns an array describing the system metadata of the document dataset.
 
Returns an array describing the system metadata of the document dataset.
  
Line 374: Line 374:
 
====write_copy====
 
====write_copy====
  
  $success = $stored->write_copy( $filename )
+
  $success = $file->write_copy( $filename )
 
Write a copy of this file to <tt>$filename</tt>.
 
Write a copy of this file to <tt>$filename</tt>.
  
Line 389: Line 389:
 
====write_copy_fh====
 
====write_copy_fh====
  
  $success = $stored-&gt;write_copy_fh( $filehandle )
+
  $success = $file-&gt;write_copy_fh( $filehandle )
 
Write a copy of this file to <tt>$filehandle</tt>.
 
Write a copy of this file to <tt>$filehandle</tt>.
  
Line 471: Line 471:
 
====add_plugin_copy====
 
====add_plugin_copy====
  
  $stored-&gt;add_plugin_copy( $plugin, $sourceid )
+
  $file-&gt;add_plugin_copy( $plugin, $sourceid )
 
Add a copy of this file stored using <tt>$plugin</tt> identified by  <tt>$sourceid</tt>.
 
Add a copy of this file stored using <tt>$plugin</tt> identified by  <tt>$sourceid</tt>.
  
Line 484: Line 484:
 
====remove_plugin_copy====
 
====remove_plugin_copy====
  
  $stored-&gt;remove_plugin_copy( $plugin )
+
  $file-&gt;remove_plugin_copy( $plugin )
 
Remove the copy of this file stored using <tt>$plugin</tt>.
 
Remove the copy of this file stored using <tt>$plugin</tt>.
  
Line 497: Line 497:
 
====get_file====
 
====get_file====
  
  $success = $stored-&gt;get_file( $f, [ $offset, $n ] )
+
  $success = $file-&gt;get_file( $f, [ $offset, $n ] )
 
Get the contents of the stored file.
 
Get the contents of the stored file.
  

Revision as of 17:11, 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

$fields = 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 = $file->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 = $file->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

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

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

User Comments


remove_plugin_copy

$file->remove_plugin_copy( $plugin )

Remove the copy of this file stored using $plugin.

User Comments


get_file

$success = $file->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


SEE ALSO

EPrints::DataObj and EPrints::DataSet.

User Comments


COPYRIGHT

© Copyright 2022 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/.

User Comments