includes/filerepo/README

   1 Some quick notes on the file/repository architecture.
   2
   3 Functionality is, as always, driven by data model.
   4
   5 * The repository object stores configuration information about a file storage
   6   method.
   7
   8 * The file object is a process-local cache of information about a particular
   9   file.
  10
  11 Thus the file object is the primary public entry point for obtaining information
  12 about files, since access via the file object can be cached, whereas access via
  13 the repository should not be cached.
  14
  15 Functions which can act on any file specified in their parameters typically find
  16 their place either in the repository object, where reference to
  17 repository-specific configuration is needed, or in static members of File or
  18 FileRepo, where no such configuration is needed.
  19
  20 File objects are generated by a factory function from the repository. The
  21 repository thus has full control over the behaviour of its subsidiary file
  22 class, since it can subclass the file class and override functionality at its
  23 whim. Thus there is no need for the File subclass to query its parent repository
  24 for information about repository-class-dependent behaviour -- the file subclass
  25 is generally fully aware of the static preferences of its repository. Limited
  26 exceptions can be made to this rule to permit sharing of functions, or perhaps
  27 even entire classes, between repositories.
  28
  29 These rules alone still do lead to some ambiguity -- it may not be clear whether
  30 to implement some functionality in a repository function with a filename
  31 parameter, or in the file object itself.
  32
  33 So we introduce the following rule: the file subclass is smarter than the
  34 repository subclass. The repository should in general provide a minimal API
  35 needed to access the storage backend efficiently.
  36
  37 In particular, note that I have not implemented any database access in
  38 LocalRepo.php. LocalRepo provides only file access, and LocalFile provides
  39 database access and higher-level functions such as cache management.
  40
  41 Tim Starling, June 2007
  42
  43 Structure:
  44
  45 File.php defines an abstract class File.
  46     ForeignAPIFile.php extends File.
  47     LocalFile.php extends File.
  48         ForeignDBFile.php extends LocalFile
  49         Image.php extends LocalFile
  50     UnregisteredLocalFile.php extends File.
  51 FileRepo.php defined an abstract class FileRepo.
  52     ForeignAPIRepo.php extends FileRepo
  53     FSRepo extends FileRepo
  54         LocalRepo.php extends FSRepo
  55             ForeignDBRepo.php extends LocalRepo
  56             ForeignDBViaLBRepo.php extends LocalRepo
  57     NullRepo extends FileRepo
  58
  59 Russ Nelson, March 2011