Editing StorageController (section)

== The Storage Controller & API (0.2 Alpha) ==

   NOTES: This module is where the selection process of storage plugin takes place. Currently there is no configuration capability
   on a per archive basis thus the controller can only be customised by editing this source file. At the moment it looks through the   
   storage plugins directory and uses the first storage plug-in it finds for everything! 

LOCATION: /lib/storage/default.xml 

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.

Each data stream is located at a repository unique location constructed from the data object id, bucket name and file name. This may be turned into a URI by the storage layer to achieve global uniqueness (e.g. by using the repository's hostname).
Multiple Storage Mediums

The storage layer may make use of multiple storage back-ends. To assist locating the correct place to store and retrieve streams the API requires the EPrints object and a "bucket" name.

The EPrints object passed to the storage API may be used to choose different storage mediums or to add metadata to the stored stream (e.g. if the storage back end is another repository).

The bucket is a string that identifies classes of streams. For instance EPrints::DataObj::Document objects (currently) have "data" and "thumbnail" buckets for storing files and thumbnails respectively.
Revisions

The storage layer may store multiple revisions located at the same filename.

If the storage medium supports revisioning it is expected that repeated store() calls to the same location will result in multiple revisions. A retrieve() call without any revision will always return the data stored in the last store() call.

METHODS

  $store = EPrints::Storage->new( $session )
    Create a new storage object for $session. Should not be used directly, see EPrints::Session.
   
  $success = $store->store( $fileobj, $filehandle )
    Read from and store all data from $filehandle for $fileobj. Returns false on error.
    
  $filehandle = $store->retrieve( $fileobj [, $revision ] )
    Retrieve a $filehandle to the object stored for $fileobj. If no $revision is specified returns the revision in $fileobj.
  
  $success = $store->delete( $fileobj [, $revision ] )
    Delete the object stored for $fileobj. If no $revision is specified deletes the revision in $fileobj.
   
  $filename = $store->get_local_copy( $fileobj [, $revision ] )
    Return the name of a local copy of the file (may be a File::Temp object). Will retrieve and cache the remote object if necessary.
  
  $url = $store->get_remote_copy( $fileobj, $sourceid )
    Returns an alternative URL for this file (must be publicly accessible). Returns undef if no such copy is available.