/ 
SReview-0.12.0
River stage zero No dependents
/ SReview::Files::Collection::Base

NAME

SReview::Files::Collection::Base - Base class for file collections

DESCRIPTION

This class is used as a base class for all SReview::Files::Collection classes.

For SReview, a collection is a "container" of files, like a directory. The implementation requires that each file object in the collection has a URL created by the collection's "baseurl" property, followed by a slash, and the relative name of the file.

PROPERTIES

children

An array of SReview::Files::Base objects, one for each file in the collection.

This is a lazy property, and will be computed on demand based on the files that are, at that point in time, actually available in the collection, through its builder, _probe_children, which needs to be implemented by the implementing class if indexing of files is supported.

Some implementations do not support this. These implementations (e.g., SReview::Files::Collection::HTTP) do not need to implement the _probe_children method.

Note: the definition allows for collections to contain more collections. However, this turned out to be problematic, and so the current implementation expects that the "children" property of collections created by "create" in SReview::Files::Factory only returns SReview::Files::Access objects. However, as some implementations might want to internally use a collection that does use a collection of collections, this is not enforced at the API level.

baseurl

The base URL of the collection. Either this property or the "globpattern" one is required.

Defaults to the leading part of the "globpattern" up to the last character before the first * character, with trailing slashes, if any, removed.

Need not be a valid absolute URL; e.g., the SReview::Files::Collection::direct implementation uses an absolute path that contains the collection.

globpattern

The globpattern is used by some implementations' "children" property to find the files in the collection.

Either this property or the "baseurl" one is required.

fileclass

The name of the SReview::Files::Access::Base subclass used for files found in the collection.

Required.

collection_name

The name of the collection. Used in some debugging methods.

METHODS

get_file

Helper method to create an object of the "fileclass" class for files that already exist in the collection.

Any valid properties for the "fileclass" class can be specified as arguments. It explicitly sets the "create" property to false.

add_file

Helper method to create an object of the "fileclass" class for files that do not yet exist in the collection.

Any valid properties for the "fileclass" class can be specified as arguments. It explicitly sets the "create" property to true.

has_file

Helper method to determine if the file with the given "relname" property exists in the collection.

The default implementation is an inefficient search over the list of files returned by the "children" property. Where possible, subclasses should implement a more efficient method of testing the file's existence.

delete_files

Helper method to delete multiple files in the collection.

Can be called in one of two ways.

  • Use the files argument to pass an arrayref of absolute filenames:

    $coll->delete_files(files => ["/foo/bar", "/foo/baz"]);

  • Use the relnames argument to pass an arrayref of relative filenames:

    $coll->delete_files(relnames => ["bar", "baz"]);

Either way, the list of files to delete must be within the collection; any files that are not a part of the collection will not be deleted.

A file is deleted if it shares a prefix with one of the items in the list; e.g., if the absolute path of the collection is /foo, and the collection contained files "bar/test123", "baz", and "bazy", then in the above two examples all those files would be removed.

If a prefix passed does not exist within the collection, a warning is printed but this will not be considered an error.

delete

Helper method to delete the collection.

The default implementation only deletes all the files in the collection. Subclasses should implement deleting the collection itself (e.g., by deleting an S3 bucket, or deleting the directory in which the files of the collection are found).