⧼vector-jumptocontent⧽

API:EPrints/Storage: Difference between revisions

From EPrints Documentation
← Older editNewer edit →
No edit summary
No edit summary
Line 4: Line 4:




<!-- Pod2Wiki=_private_ -->{{API:Unstable}}<!-- Pod2Wiki=head_name -->
<!-- Pod2Wiki=_private_ -->{{API:Unstable}}
 
<!-- Pod2Wiki=head_name -->
==NAME==
==NAME==
'''EPrints::Storage''' - store and retrieve objects in the storage engine
'''EPrints::Storage''' - store and retrieve objects in the storage engine


<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>
<!-- Edit below this comment -->
<!-- Edit below this comment -->




<!-- Pod2Wiki= -->
<!-- Pod2Wiki= -->
</div>
<!-- Pod2Wiki=head_synopsis -->
<!-- Pod2Wiki=head_synopsis -->
==SYNOPSIS==
==SYNOPSIS==
  my $store = $repository-&gt;storage();
<source lang="perl">my $store = $repository->storage();
 
 
  $store-&gt;store(
$store->store(
    $fileobj,   # file object
$fileobj, # file object
    "diddle.pdf", # filename
"diddle.pdf", # filename
    $fh       # file handle
$fh # file handle
  );
);</source>
 
 
<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>
<!-- Edit below this comment -->
<!-- Edit below this comment -->




<!-- Pod2Wiki= -->
<!-- Pod2Wiki= -->
</div>
<!-- Pod2Wiki=head_description -->
<!-- Pod2Wiki=head_description -->
==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.


<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>
<!-- Edit below this comment -->
<!-- Edit below this comment -->




<!-- Pod2Wiki= -->
<!-- Pod2Wiki= -->
</div>
<!-- Pod2Wiki=head_methods -->
<!-- Pod2Wiki=head_methods -->
==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%; '>
<!-- Pod2Wiki=head_new -->
<span style='display:none'>User Comments</span>
===new===
<!-- Edit below this comment -->


<source lang="perl">$store = EPrints::Storage->new( $repository )


<!-- Pod2Wiki= -->
</source>
</div>
<!-- Pod2Wiki=item_new -->
===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]].


<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>
<!-- Edit below this comment -->
<!-- Edit below this comment -->




<!-- Pod2Wiki= -->
<!-- Pod2Wiki= -->
</div>
<!-- Pod2Wiki=head_store -->
<!-- Pod2Wiki=item_store -->
===store===
===store===


$len = $store-&gt;store( $fileobj, CODEREF )
<source lang="perl">$len = $store->store( $fileobj, CODEREF [, $offset ] )
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.
 
</source>
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 read.
Returns undef if the file couldn't be stored, otherwise the number of bytes actually written.


<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>
<!-- Edit below this comment -->
<!-- Edit below this comment -->




<!-- Pod2Wiki= -->
<!-- Pod2Wiki= -->
</div>
<!-- Pod2Wiki=head_retrieve -->
<!-- Pod2Wiki=item_retrieve -->
===retrieve===
===retrieve===


$success = $store-&gt;retrieve( $fileobj, $offset, $n, CALLBACK )
<source lang="perl">$success = $store->retrieve( $fileobj, $offset, $n, CALLBACK )
 
</source>
Retrieve the contents of the $fileobj starting at $offset for $n bytes.
Retrieve the contents of the $fileobj starting at $offset for $n bytes.


CALLBACK = $rc = &amp;f( BUFFER )
CALLBACK = $rc = &amp;f( BUFFER )


<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>
<!-- Edit below this comment -->
<!-- Edit below this comment -->




<!-- Pod2Wiki= -->
<!-- Pod2Wiki= -->
</div>
<!-- Pod2Wiki=head_delete -->
<!-- Pod2Wiki=item_delete -->
===delete===
===delete===


$success = $store-&gt;delete( $fileobj )
<source lang="perl">$success = $store->delete( $fileobj )
 
</source>
Delete all object copies stored for $fileobj.
Delete all object copies stored for $fileobj.


<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>
<!-- Edit below this comment -->
<!-- Edit below this comment -->




<!-- Pod2Wiki= -->
<!-- Pod2Wiki= -->
</div>
<!-- Pod2Wiki=head_delete_copy -->
<!-- Pod2Wiki=item_delete_copy -->
===delete_copy===
===delete_copy===


$ok = $store-&gt;delete_copy( $plugin, $fileobj )
<source lang="perl">$ok = $store->delete_copy( $plugin, $fileobj )
 
</source>
Delete the copy of this file stored in $plugin.
Delete the copy of this file stored in $plugin.


<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>
<!-- Edit below this comment -->
<!-- Edit below this comment -->




<!-- Pod2Wiki= -->
<!-- Pod2Wiki= -->
</div>
<!-- Pod2Wiki=head_get_local_copy -->
<!-- Pod2Wiki=item_get_local_copy -->
===get_local_copy===
===get_local_copy===


$filename = $store-&gt;get_local_copy( $fileobj )
<source lang="perl">$fh = $store->get_local_copy( $fileobj )
Return the name of a local copy of the file.
 
</source>
Return a local copy of the file. Potentially expensive if the file has to be retrieved.


Will retrieve and cache the remote object using {{API:PodLink|file=File/Temp|package_name=File::Temp|section=|text=File::Temp}} if necessary.
Stringifying $fh will give the full path to the local file, which may be useful for calling external tools (see {{API:PodLink|file=File/Temp|package_name=File::Temp|section=|text=File::Temp}}).


Returns undef if retrieval failed.
Returns undef if retrieval failed.


<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>
<!-- Edit below this comment -->
<!-- Edit below this comment -->




<!-- Pod2Wiki= -->
<!-- Pod2Wiki= -->
</div>
<!-- Pod2Wiki=head_get_remote_copy -->
<!-- Pod2Wiki=item_get_remote_copy -->
===get_remote_copy===
===get_remote_copy===


$url = $store-&gt;get_remote_copy( $fileobj )
<source lang="perl">$url = $store->get_remote_copy( $fileobj )
 
</source>
Returns a URL from which this file can be accessed.
Returns a URL from which this file can be accessed.


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


<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>
<!-- Edit below this comment -->
<!-- Edit below this comment -->




<!-- Pod2Wiki= -->
<!-- Pod2Wiki= -->
</div>
<!-- Pod2Wiki=head_get_plugins -->
<!-- Pod2Wiki=item_get_plugins -->
===get_plugins===
===get_plugins===


@plugins = $store-&gt;get_plugins( $fileobj )
<source lang="perl">@plugins = $store->get_plugins( $fileobj )
 
</source>
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.


<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>
<!-- Edit below this comment -->
<!-- Edit below this comment -->




<!-- Pod2Wiki= -->
<!-- Pod2Wiki= -->
</div>
<!-- Pod2Wiki=head_copy -->
<!-- Pod2Wiki=item_copy -->
===copy===
===copy===


$ok = $store-&gt;copy( $plugin, $fileobj )
<source lang="perl">$ok = $store->copy( $plugin, $fileobj )
 
</source>
Copy the contents of $fileobj into another storage $plugin.
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.
Returns 1 on success, 0 on failure and -1 if a copy already exists in $plugin.


<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>
<!-- Edit below this comment -->
<!-- Edit below this comment -->




<!-- Pod2Wiki= -->
<!-- Pod2Wiki= -->
</div>
<!-- Pod2Wiki=head_open_write -->
<!-- Pod2Wiki=item_open_write -->
===open_write===
===open_write===


$ok = $storage-&gt;open_write( $fileobj )
<source lang="perl">$ok = $storage->open_write( $fileobj [, $offset ] )
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).
 
</source>
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).


<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>
<!-- Edit below this comment -->
<!-- Edit below this comment -->




<!-- Pod2Wiki= -->
<!-- Pod2Wiki= -->
</div>
<!-- Pod2Wiki=head_write -->
<!-- Pod2Wiki=item_write -->
===write===
===write===


$ok = $storage-&gt;write( $fileobj, $buffer )
<source lang="perl">$ok = $storage->write( $fileobj, $buffer )
Write $buffer to the storage plugin(s).
 
</source>
Write $buffer to the storage plugin(s), starting from the previously written data.


<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>
<!-- Edit below this comment -->
<!-- Edit below this comment -->




<!-- Pod2Wiki= -->
<!-- Pod2Wiki= -->
</div>
<!-- Pod2Wiki=head_close_write -->
<!-- Pod2Wiki=item_close_write -->
===close_write===
===close_write===


$ok = $storage-&gt;close_write( $fileobj );
<source lang="perl">$ok = $storage->close_write( $fileobj );
 
</source>
Finish writing to the storage plugin(s) for $fileobj.
Finish writing to the storage plugin(s) for $fileobj.


<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>
<!-- Edit below this comment -->
<!-- Edit below this comment -->




<!-- Pod2Wiki= -->
<!-- Pod2Wiki= -->
</div>
<!-- Pod2Wiki=head_copyright -->
<!-- Pod2Wiki=head_copyright -->
==COPYRIGHT==
==COPYRIGHT==
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
Copyright 2000-2011 University of Southampton.
<span style='display:none'>User Comments</span>
 
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/.
 
<!-- Edit below this comment -->
<!-- Edit below this comment -->




<!-- Pod2Wiki= -->
<!-- Pod2Wiki= -->
</div>
<!-- Pod2Wiki=_postamble_ -->
<!-- Pod2Wiki=_postamble_ --><!-- Edit below this comment -->
<!-- Edit below this comment -->

Revision as of 09:56, 22 January 2013

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.

NAME

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


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

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.

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.


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

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) to use for $fileobj. 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.

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


write

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

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


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



Retrieved from "https://wiki.ext-9.eprints-hosting.org/w/index.php?title=API:EPrints/Storage&oldid=10686"