Difference between revisions of "API:EPrints/Storage"

From EPrints Documentation
Jump to: navigation, search
Line 53: Line 53:
 
</div>
 
</div>
 
<!-- Pod2Wiki=item_new -->
 
<!-- Pod2Wiki=item_new -->
===$store = EPrints::Storage-&gt;new( $repository )===
+
===new===
  
 +
$store = EPrints::Storage-&gt;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 65: Line 66:
 
</div>
 
</div>
 
<!-- Pod2Wiki=item_store -->
 
<!-- Pod2Wiki=item_store -->
===$len = $store-&gt;store( $fileobj, CODEREF )===
+
===store===
  
 +
$len = $store-&gt;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 79: Line 81:
 
</div>
 
</div>
 
<!-- Pod2Wiki=item_retrieve -->
 
<!-- Pod2Wiki=item_retrieve -->
===$success = $store-&gt;retrieve( $fileobj, CALLBACK )===
+
===retrieve===
  
 +
$success = $store-&gt;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%; '>
 
<span style='display:none'>User Comments</span>
 
<span style='display:none'>User Comments</span>
Line 89: Line 92:
 
</div>
 
</div>
 
<!-- Pod2Wiki=item_delete -->
 
<!-- Pod2Wiki=item_delete -->
===$success = $store-&gt;delete( $fileobj )===
+
===delete===
  
 +
$success = $store-&gt;delete( $fileobj )
 
Delete all object copies stored for $fileobj.
 
Delete all object copies stored for $fileobj.
  
Line 101: Line 105:
 
</div>
 
</div>
 
<!-- Pod2Wiki=item_delete_copy -->
 
<!-- Pod2Wiki=item_delete_copy -->
===$ok = $store-&gt;delete_copy( $plugin, $fileobj )===
+
===delete_copy===
  
 +
$ok = $store-&gt;delete_copy( $plugin, $fileobj )
 
Delete the copy of this file stored in $plugin.
 
Delete the copy of this file stored in $plugin.
  
Line 113: Line 118:
 
</div>
 
</div>
 
<!-- Pod2Wiki=item_get_local_copy -->
 
<!-- Pod2Wiki=item_get_local_copy -->
===$filename = $store-&gt;get_local_copy( $fileobj )===
+
===get_local_copy===
  
 +
$filename = $store-&gt;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 129: Line 135:
 
</div>
 
</div>
 
<!-- Pod2Wiki=item_get_remote_copy -->
 
<!-- Pod2Wiki=item_get_remote_copy -->
===$url = $store-&gt;get_remote_copy( $fileobj )===
+
===get_remote_copy===
  
 +
$url = $store-&gt;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 143: Line 150:
 
</div>
 
</div>
 
<!-- Pod2Wiki=item_get_plugins -->
 
<!-- Pod2Wiki=item_get_plugins -->
===@plugins = $store-&gt;get_plugins( $fileobj )===
+
===get_plugins===
  
 +
@plugins = $store-&gt;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 155: Line 163:
 
</div>
 
</div>
 
<!-- Pod2Wiki=item_copy -->
 
<!-- Pod2Wiki=item_copy -->
===$ok = $store-&gt;copy( $plugin, $fileobj )===
+
===copy===
  
 +
$ok = $store-&gt;copy( $plugin, $fileobj )
 
Copy the contents of $fileobj into another storage $plugin.
 
Copy the contents of $fileobj into another storage $plugin.
  
Line 169: Line 178:
 
</div>
 
</div>
 
<!-- Pod2Wiki=item_open_write -->
 
<!-- Pod2Wiki=item_open_write -->
===$ok = $storage-&gt;open_write( $fileobj )===
+
===open_write===
  
 +
$ok = $storage-&gt;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 181: Line 191:
 
</div>
 
</div>
 
<!-- Pod2Wiki=item_write -->
 
<!-- Pod2Wiki=item_write -->
===$ok = $storage-&gt;write( $fileobj, $buffer )===
+
===write===
  
 +
$ok = $storage-&gt;write( $fileobj, $buffer )
 
Write $buffer to the storage plugin(s).
 
Write $buffer to the storage plugin(s).
  
Line 193: Line 204:
 
</div>
 
</div>
 
<!-- Pod2Wiki=item_close_write -->
 
<!-- Pod2Wiki=item_close_write -->
===$ok = $storage-&gt;close_write( $fileobj );===
+
===close_write===
  
 +
$ok = $storage-&gt;close_write( $fileobj );
 
Finish writing to the storage plugin(s) for $fileobj.
 
Finish writing to the storage plugin(s) for $fileobj.
  

Revision as of 13:15, 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


API: Core API

Latest Source Code (3.3, 3.2) | 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.

NAME

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

User Comments


SYNOPSIS

 my $store = $repository->storage();
 
 $store->store(
   $fileobj,    # file object
   "diddle.pdf",  # filename
   $fh        # file handle
 );
 

User Comments


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.

User Comments


METHODS

User Comments


new

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

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

User Comments


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.

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

User Comments


retrieve

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

User Comments


delete

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

Delete all object copies stored for $fileobj.

User Comments


delete_copy

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

Delete the copy of this file stored in $plugin.

User Comments


get_local_copy

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

User Comments


get_remote_copy

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

User Comments


get_plugins

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

User Comments


copy

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

User Comments


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

User Comments


write

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

Write $buffer to the storage plugin(s).

User Comments


close_write

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

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

User Comments