Difference between revisions of "API:EPrints/Storage"
| Line 4: | Line 4: | ||
| − | <!-- Pod2Wiki=_private_ -->{{API:Unstable}}<!-- Pod2Wiki=head_name -->==NAME== | + | <!-- Pod2Wiki=_private_ -->{{API:Unstable}}<!-- Pod2Wiki=head_name --> |
| + | ==NAME== | ||
'''EPrints::Storage''' - store and retrieve objects in the storage engine | '''EPrints::Storage''' - store and retrieve objects in the storage engine | ||
| Line 12: | Line 13: | ||
| + | </div> | ||
| + | <!-- Pod2Wiki= --> | ||
</div> | </div> | ||
<!-- Pod2Wiki=_private_ -->This should be inserted verbatum into the Wiki page. | <!-- Pod2Wiki=_private_ -->This should be inserted verbatum into the Wiki page. | ||
| − | <!-- Pod2Wiki=head_synopsis -->==SYNOPSIS== | + | <!-- Pod2Wiki=head_synopsis --> |
| + | ==SYNOPSIS== | ||
my $store = $repository->storage(); | my $store = $repository->storage(); | ||
| Line 30: | Line 34: | ||
| + | </div> | ||
| + | <!-- Pod2Wiki= --> | ||
</div> | </div> | ||
| − | <!-- Pod2Wiki=head_description -->==DESCRIPTION== | + | <!-- Pod2Wiki=head_description --> |
| + | ==DESCRIPTION== | ||
This module is the storage control layer which uses [[API:EPrints/Plugin/Storage|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. | This module is the storage control layer which uses [[API:EPrints/Plugin/Storage|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. | ||
| Line 40: | Line 47: | ||
| + | </div> | ||
| + | <!-- Pod2Wiki= --> | ||
</div> | </div> | ||
| − | <!-- Pod2Wiki=head_methods -->==METHODS== | + | <!-- Pod2Wiki=head_methods --> |
| + | ==METHODS== | ||
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce; padding: 0em 1em 0em 1em; font-size: 80%; '> | <div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce; padding: 0em 1em 0em 1em; font-size: 80%; '> | ||
<span style='display:none'>User Comments</span> | <span style='display:none'>User Comments</span> | ||
| Line 48: | Line 58: | ||
| + | </div> | ||
| + | <!-- Pod2Wiki= --> | ||
</div> | </div> | ||
| − | <!-- Pod2Wiki=item_new -->===$store = EPrints::Storage->new( $repository )=== | + | <!-- Pod2Wiki=item_new --> |
| + | ===$store = EPrints::Storage->new( $repository )=== | ||
Create a new storage object for $repository. Should not be used directly, see [[API:EPrints/Session|EPrints::Session]]. | Create a new storage object for $repository. Should not be used directly, see [[API:EPrints/Session|EPrints::Session]]. | ||
| Line 59: | Line 72: | ||
| + | </div> | ||
| + | <!-- Pod2Wiki= --> | ||
</div> | </div> | ||
| − | <!-- Pod2Wiki=item_store -->===$len = $store->store( $fileobj, CODEREF )=== | + | <!-- Pod2Wiki=item_store --> |
| + | ===$len = $store->store( $fileobj, CODEREF )=== | ||
Read from and store all data from CODEREF for $fileobj. The '''filesize''' field in $fileobj must be set at the expected number of bytes to read from CODEREF. | Read from and store all data from CODEREF for $fileobj. The '''filesize''' field in $fileobj must be set at the expected number of bytes to read from CODEREF. | ||
| Line 72: | Line 88: | ||
| + | </div> | ||
| + | <!-- Pod2Wiki= --> | ||
</div> | </div> | ||
| − | <!-- Pod2Wiki=item_retrieve -->===$success = $store->retrieve( $fileobj, CALLBACK )=== | + | <!-- Pod2Wiki=item_retrieve --> |
| + | ===$success = $store->retrieve( $fileobj, CALLBACK )=== | ||
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce; padding: 0em 1em 0em 1em; font-size: 80%; '> | <div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce; padding: 0em 1em 0em 1em; font-size: 80%; '> | ||
| Line 81: | Line 100: | ||
| + | </div> | ||
| + | <!-- Pod2Wiki= --> | ||
</div> | </div> | ||
| − | <!-- Pod2Wiki=item_delete -->===$success = $store->delete( $fileobj )=== | + | <!-- Pod2Wiki=item_delete --> |
| + | ===$success = $store->delete( $fileobj )=== | ||
Delete all object copies stored for $fileobj. | Delete all object copies stored for $fileobj. | ||
| Line 92: | Line 114: | ||
| + | </div> | ||
| + | <!-- Pod2Wiki= --> | ||
</div> | </div> | ||
| − | <!-- Pod2Wiki=item_delete_copy -->===$ok = $store->delete_copy( $plugin, $fileobj )=== | + | <!-- Pod2Wiki=item_delete_copy --> |
| + | ===$ok = $store->delete_copy( $plugin, $fileobj )=== | ||
Delete the copy of this file stored in $plugin. | Delete the copy of this file stored in $plugin. | ||
| Line 103: | Line 128: | ||
| + | </div> | ||
| + | <!-- Pod2Wiki= --> | ||
</div> | </div> | ||
| − | <!-- Pod2Wiki=item_get_local_copy -->===$filename = $store->get_local_copy( $fileobj )=== | + | <!-- Pod2Wiki=item_get_local_copy --> |
| + | ===$filename = $store->get_local_copy( $fileobj )=== | ||
Return the name of a local copy of the file. | Return the name of a local copy of the file. | ||
| Line 118: | Line 146: | ||
| + | </div> | ||
| + | <!-- Pod2Wiki= --> | ||
</div> | </div> | ||
| − | <!-- Pod2Wiki=item_get_remote_copy -->===$url = $store->get_remote_copy( $fileobj )=== | + | <!-- Pod2Wiki=item_get_remote_copy --> |
| + | ===$url = $store->get_remote_copy( $fileobj )=== | ||
Returns a URL from which this file can be accessed. | Returns a URL from which this file can be accessed. | ||
| Line 131: | Line 162: | ||
| + | </div> | ||
| + | <!-- Pod2Wiki= --> | ||
</div> | </div> | ||
| − | <!-- Pod2Wiki=item_get_plugins -->===@plugins = $store->get_plugins( $fileobj )=== | + | <!-- Pod2Wiki=item_get_plugins --> |
| + | ===@plugins = $store->get_plugins( $fileobj )=== | ||
Returns the [[API:EPrints/Plugin/Storage|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. | Returns the [[API:EPrints/Plugin/Storage|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. | ||
| Line 142: | Line 176: | ||
| + | </div> | ||
| + | <!-- Pod2Wiki= --> | ||
</div> | </div> | ||
| − | <!-- Pod2Wiki=item_copy -->===$ok = $store->copy( $plugin, $fileobj )=== | + | <!-- Pod2Wiki=item_copy --> |
| + | ===$ok = $store->copy( $plugin, $fileobj )=== | ||
Copy the contents of $fileobj into another storage $plugin. | Copy the contents of $fileobj into another storage $plugin. | ||
| Line 155: | Line 192: | ||
| + | </div> | ||
| + | <!-- Pod2Wiki= --> | ||
</div> | </div> | ||
| − | <!-- Pod2Wiki=item_open_write -->===$ok = $storage->open_write( $fileobj )=== | + | <!-- Pod2Wiki=item_open_write --> |
| + | ===$ok = $storage->open_write( $fileobj )=== | ||
Start a write session for $fileobj. $fileobj must have at least the "filesize" property set (which is the number of bytes that will be written). | Start a write session for $fileobj. $fileobj must have at least the "filesize" property set (which is the number of bytes that will be written). | ||
| Line 166: | Line 206: | ||
| + | </div> | ||
| + | <!-- Pod2Wiki= --> | ||
</div> | </div> | ||
| − | <!-- Pod2Wiki=item_write -->===$ok = $storage->write( $fileobj, $buffer )=== | + | <!-- Pod2Wiki=item_write --> |
| + | ===$ok = $storage->write( $fileobj, $buffer )=== | ||
Write $buffer to the storage plugin(s). | Write $buffer to the storage plugin(s). | ||
| Line 177: | Line 220: | ||
| + | </div> | ||
| + | <!-- Pod2Wiki= --> | ||
</div> | </div> | ||
| − | <!-- Pod2Wiki=item_close_write -->===$ok = $storage->close_write( $fileobj );=== | + | <!-- Pod2Wiki=item_close_write --> |
| + | ===$ok = $storage->close_write( $fileobj );=== | ||
Finish writing to the storage plugin(s) for $fileobj. | Finish writing to the storage plugin(s) for $fileobj. | ||
| Line 188: | Line 234: | ||
| + | </div> | ||
| + | <!-- Pod2Wiki= --> | ||
</div> | </div> | ||
<!-- Pod2Wiki=_postamble_ --><!-- Edit below this comment --> | <!-- Pod2Wiki=_postamble_ --><!-- Edit below this comment --> | ||
Revision as of 12:08, 25 February 2010
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
 |
The interface for this module has not been finalised and may change in the future. |
Contents
- 1 NAME
- 2 SYNOPSIS
- 3 DESCRIPTION
- 4 METHODS
- 4.1 $store = EPrints::Storage->new( $repository )
- 4.2 $len = $store->store( $fileobj, CODEREF )
- 4.3 $success = $store->retrieve( $fileobj, CALLBACK )
- 4.4 $success = $store->delete( $fileobj )
- 4.5 $ok = $store->delete_copy( $plugin, $fileobj )
- 4.6 $filename = $store->get_local_copy( $fileobj )
- 4.7 $url = $store->get_remote_copy( $fileobj )
- 4.8 @plugins = $store->get_plugins( $fileobj )
- 4.9 $ok = $store->copy( $plugin, $fileobj )
- 4.10 $ok = $storage->open_write( $fileobj )
- 4.11 $ok = $storage->write( $fileobj, $buffer )
- 4.12 $ok = $storage->close_write( $fileobj );
NAME
EPrints::Storage - store and retrieve objects in the storage engine
This should be inserted verbatum into the Wiki page.
SYNOPSIS
my $store = $repository->storage(); $store->store( $fileobj, # file object "diddle.pdf", # filename $fh # file handle );
DESCRIPTION
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.
METHODS
$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 )
Read from and store all data from CODEREF for $fileobj. The filesize field in $fileobj must be set at the expected number of bytes to read from CODEREF.
Returns undef if the file couldn't be stored, otherwise the number of bytes read.
$success = $store->retrieve( $fileobj, CALLBACK )
$success = $store->delete( $fileobj )
Delete all object copies stored for $fileobj.
$ok = $store->delete_copy( $plugin, $fileobj )
Delete the copy of this file stored in $plugin.
$filename = $store->get_local_copy( $fileobj )
Return the name of a local copy of the file.
Will retrieve and cache the remote object using File::Temp if necessary.
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 )
Start a write session for $fileobj. $fileobj must have at least the "filesize" property set (which is the number of bytes that will be written).
$ok = $storage->write( $fileobj, $buffer )
Write $buffer to the storage plugin(s).
$ok = $storage->close_write( $fileobj );
Finish writing to the storage plugin(s) for $fileobj.
