NAME
SReview::Files::Access::Base - Base class for file access methods
DESCRIPTION
This class is used as a base class for all SReview::Files classes that provide access to files (as opposed to directories). It should not be used directly, but it defines the API to access files using the SReview::Files API.
PROPERTIES
relname
The relative name of the file, inside the collection. Required at object creation time. Should contain the full path from the root of the collection.
filename
An absolute pathname that points to a readable version of the data file, on the local filesystem. Its builder, _get_file, must be implemented by subclasses.
If the file is not currently available on the local filesystem, the _get_file method should do whatever is required to ensure that it somehow is (e.g., download the file to a temporary directory), and then return the filename to the file that it now made available. The created file must have the same extension so that other parts of SReview can correctly recognize the file type, but is not otherwise required to have any part of "relname" in the name.
If the "create" property is true, the caller wants to create or overwrite the contents of the file. In this case, the _get_file method should not download a file, but should still return a filename with the correct extension.
mtime
The modification time of the file. Used by sreview-detect to determine if a file has changed since it was last seen.
baseurl
A copy of the containing collection's baseurl property. Done as an optimization, so that an implementation doesn't have to look up the collection in use in order to build the full URL when needed.
basepath
The base path of the filename; the part that comes before the "valid_path_filename". For the SReview::Files::Access::direct implementation, this is the same as "baseurl". For other implementations, this could be the name of a temporary directory or something along those lines.
create
Boolean. The caller should set this property to true if it wants to write to the file, and to false if it wants to read from the file.
Creating an object that can be used both for reading and writing at the same time is not supported.
is_stored
Boolean. Indicates that the file has been uploaded to the server, if required. Used by the destructor to detect forgotten "store_file" calls, and make them implicit.
METHODS
valid_path_filename
The valid_path_filename method should be implemented by subclasses to return the path to the file on the local filesystem. It differs from the "filename" property in that the returned filename must end with the value of the "relname" property. However, it may do this by way of a symlink to the file pointed to by the "filename" property.
Future versions of this API may implement this as a lazy property rather than a subroutine.
store_file
This method should be implemented by subclasses to write the contents of the file to the correct location on the server. After successfully uploading the file, the "is_stored" property should be set to true.
Read-only implementations of the SReview::Files API (e.g., SReview::Files::Access::HTTP) do not need to provide this method.
If no upload is required, the method should still set the "is_stored" property to true.
delete
This method should be implemented by subclasses to delete the file from the collection.
Read-only implementations of the SReview::Files API (e.g., SReview::Files::Access::HTTP) do not need to provide this method.
AUTHOR
Wouter Verhelst <w@uter.be>