Some notes on architecture.

diff --git a/includes/filerepo/README b/includes/filerepo/README
new file mode 100644 (file)
index 0000000..d40eaad
--- /dev/null
+++ b/includes/filerepo/README
@@ -0,0 +1,41 @@
+Some quick notes on the file/repository architecture.\r
+\r
+Functionality is, as always, driven by data model. \r
+\r
+* The repository object stores configuration information about a file storage \r
+  method.\r
+\r
+* The file object is a process-local cache of information about a particular\r
+  file.\r
+\r
+Thus the file object is the primary public entry point for obtaining information\r
+about files, since access via the file object can be cached, whereas access via\r
+the repository should not be cached.\r
+\r
+Functions which can act on any file specified in their parameters typically find\r
+their place either in the repository object, where reference to\r
+repository-specific configuration is needed, or in static members of File or\r
+FileRepo, where no such configuration is needed.\r
+\r
+File objects are generated by a factory function from the repository. The\r
+repository thus has full control over the behaviour of its subsidiary file\r
+class, since it can subclass the file class and override functionality at its\r
+whim. Thus there is no need for the File subclass to query its parent repository\r
+for information about repository-class-dependent behaviour -- the file subclass\r
+is generally fully aware of the static preferences of its repository. Limited\r
+exceptions can be made to this rule to permit sharing of functions, or perhaps\r
+even entire classes, between repositories.\r
+\r
+These rules alone still do lead to some ambiguity -- it may not be clear whether\r
+to implement some functionality in a repository function with a filename\r
+parameter, or in the file object itself. \r
+\r
+So we introduce the following rule: the file subclass is smarter than the \r
+repository subclass. The repository should in general provide a minimal API\r
+needed to access the storage backend efficiently. \r
+\r
+In particular, note that I have not implemented any database access in \r
+LocalRepo.php. LocalRepo provides only file access, and LocalFile provides \r
+database access and higher-level functions such as cache management.\r
+\r
+Tim Starling, June 2007\r