API:EPrints/Storage

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

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

NAME

EPrints::Storage - manage data streams in storage devices (storage layer)

SYNOPSIS

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

$str = "Hello, World!";
open(my $fh, "<", \$str);
$f = sub {
	read($fh, my $buffer, 6); # just to demonstrate!
	return $buffer;
};
$store->store(
	$fileobj,		# file object
	$f,				# callback
	1024,			# offset
);

DESCRIPTION

Unless you are directly manipulating how data streams are stored you should use the methods for retrieving and writing data available from EPrints::DataObj::File.

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.

Storage works on EPrints::DataObj::File objects, which record the size of the data stream and where it has been stored. Unless a specific storage back-end is used, where a file is stored depends on the storage policy which is located in lib/storage/default.xml:

<store xmlns="http://eprints.org/ep3/storage" xmlns:epc="http://eprints.org/ep3/control">
<epc:choose>
	<epc:when test="datasetid = 'document'">
		<plugin name="Local"/>
	</epc:when>
	<epc:otherwise>
		<plugin name="Local"/>
	</epc:otherwise>
</epc:choose>
</store>

The storage policy is a EP-script file that resolves to a list of one or more "plugin" elements. When storing, all matching plugins will be given the data stream to store (i.e. multiple copies). When retrieving, the first plugin to be successfully opened for reading will be used. The item context used when the storage policy is evaluated is the EPrints::DataObj::File.

Callbacks

Writing to and retrieving from data streams makes use of callback functions. This allows data to be streamed (to avoid memory overheads) and for flexibility in where data is going.

For details on the callback API see EPrints::DataObj::File/get_file and EPrints::DataObj::File/set_file for retrieving and writing respectively.

METHODS

new

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

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

store

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

Read from and store all data from CODEREF for $fileobj. If $offset is given starts writing from that point onwards.

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

Returns the number of bytes written or undef if an error occurred.

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

retrieve

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

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

CALLBACK = $rc = &f( BUFFER )

delete

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

Delete all object copies stored for $fileobj.

delete_copy

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

Delete the copy of this file stored in the storage layer $plugin.

get_local_copy

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

get_remote_copy

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

Some storage back-ends may provide direct Web access to the data stream (e.g. Amazon S3). If the back-end supports this, a user can be redirected to the storage back-end rather than downloading the file from EPrints. Internally, EPrints will always use the retrieve method.

Returns a URL from which this file can be accessed.

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

get_plugins

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

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

copy

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

Copy the contents of $fileobj into another storage $plugin. This uses retrieve and store.

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

open_write

$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).

Don't forget to close_write otherwise the handle to the write will be left open.

This, along with write and close_write, is an alternative to the store method.

write

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

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

This, along with open_write and close_write, is an alternative to the store method.

close_write

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

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

COPYRIGHT

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