Difference between revisions of "API:EPrints/Storage"

From EPrints Documentation
Jump to: navigation, search
(retrieve: Updated parameters to match existing code.)
(delete: Update list of parameters to reflect usage in current release examples.)
Line 85: Line 85:
<source lang="perl">$success = $store->delete( $fileobj )
<source lang="perl">$success = $store->delete( $fileobj, $sourceid )
Line 95: Line 95:
<!-- Pod2Wiki= -->
<!-- Pod2Wiki= -->
<!-- Pod2Wiki=head_delete_copy -->
<!-- Pod2Wiki=head_delete_copy -->

Revision as of 11:45, 20 February 2013

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

Warning The interface for this module has not been finalised and may change in the future.


EPrints::Storage - store and retrieve objects in the storage engine


my $store = $repository->storage();

	$fileobj,		# file object
	"diddle.pdf",	# filename
	$fh				# file handle


This module is the storage control layer which uses EPrints::Plugin::Storage plugins to support various storage back-ends. It enables the storage, retrieval and deletion of data streams. The maximum size of a stream is dependent on the back-end storage mechanism.



$store = EPrints::Storage->new( $repository )

Create a new storage object for $repository. Should not be used directly, see EPrints::Session.


$len = $store->store( $fileobj, CODEREF [, $offset ] )

Read from and store all data from CODEREF for $fileobj.

Behaviour is undefined if an attempt is made to write beyond $fileobj's filesize.

Returns undef if the file couldn't be stored, otherwise the number of bytes actually written.

The combination of methods open_write, write, and close_write can be used as an alternative to this method.


$success = $store->retrieve( $fileobj, $sourceid, $offset, $n, CALLBACK )

Retrieve the contents of the $fileobj starting at $offset for $n bytes.

CALLBACK = $rc = &f( BUFFER )


$success = $store->delete( $fileobj, $sourceid )

Delete all object copies stored for $fileobj.


$ok = $store->delete_copy( $plugin, $fileobj )

Delete the copy of this file stored in $plugin.


$fh = $store->get_local_copy( $fileobj )

Return a local copy of the file. Potentially expensive if the file has to be retrieved.

Stringifying $fh will give the full path to the local file, which may be useful for calling external tools (see File::Temp).

Returns undef if retrieval failed.


$url = $store->get_remote_copy( $fileobj )

Returns a URL from which this file can be accessed.

Returns undef if this file is not available via another service.


@plugins = $store->get_plugins( $fileobj )

Returns the EPrints::Plugin::Storage plugin(s) to use for $fileobj. If more than one plugin is returned they should be used in turn until one succeeds.


$ok = $store->copy( $plugin, $fileobj )

Copy the contents of $fileobj into another storage $plugin.

Returns 1 on success, 0 on failure and -1 if a copy already exists in $plugin.


$ok = $storage->open_write( $fileobj [, $offset ] )

Start a write session for $fileobj. $fileobj must have at least the "filesize" property set (which is the total number of bytes that will be written).


$ok = $storage->write( $fileobj, $buffer )

Write $buffer to the storage plugin(s), starting from the previously written data.


$ok = $storage->close_write( $fileobj );

Finish writing to the storage plugin(s) for $fileobj.


Copyright 2000-2011 University of Southampton.

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

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.

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/.