-
Notifications
You must be signed in to change notification settings - Fork 21
Components
This wiki describes in detail the various components that will be needed to build the Synapse R client
A universally accessible variable store used to manage configuration parameters, login credentials, etc.. This store must implement the following methods:
-
setCache(name, value) - set a parameter value
-
getCache(name) - retrieve a parameter value
-
deleteCache(name) - delete a parameter
The global variable store should be implemented as a singleton so that all methods in the package can gain access to it's contents without it being passed as a parameter.
An object that keeps track of all File Caches under the Synapse Cache directory. Possibly also keeps track of all entities cached as well?
An object that maintains the on-disk representation of Synapse entity components. This file cache will maintain the file representation of a single Synapse entity. As a minimum, the file cache must implement the following methods:
-
addFile(file, path) - add the file to the subdirectory "path". See the documentation of R's copyFile function for details on how the path argument should be interpreted. In some instances the file will be renamed and in others the path will be interpreted as a subdirectory.
-
deleteFile(filePath) - delete the file from the cache, where filePath is the path relative to the root directory of the cache
-
moveFile(oldFilePath, newFilePath) - Move an existing file
-
getFiles() - Get a listing of the files in the cache
-
createArchive() - Create a zip archive from from the cache. This method should take an optional argument indicating whether the archive should be compressed. If the archive contains more than one file, this argument should be ignored. The return value for the function should give the complete path to the archive that was created. A second optional argument should allow the caller to indicate the full file path to where the archive should be created. If this argument is omitted, the archive will be created in the root directory of the archive.
-
getFileMetadata() - Get the metadata about cache files that were unpacked from the zip file. At a minimum, this should contain a file listing as well as an indication of whether each file has change since it was last persisted or downloaded.
-
getArchiveFileMetadata() - Get the metadata about the zip archive for the entity. This should include the filename and (possibly) the up-to-date md5sum of the archive.
-
cacheFileMetaData() - Cache the file metadata to disk. This the metadata file should live at the root of the entity's archive and the metadata should be stored in JSON format.
-
loadFileMetadata() - Load the cache's file metadata to disk from a JSON file.
The File Cache should be implemented in such a way that changes made to the file cache for an entity will be reflected in all copies of that entity. An R5 implementation is one way to do this.
When a new File Cache is instantiated, the caller should have the option of specifying a root directory for the file cache. If the root directory is not specified, the file cache should store it's files in a new directory generated by a call to tempdir().
A secondary file cache constructor should be provided that takes as an argument a location object.
A third constructor should take as an argument the full path to an archive, which should be either a zip file or a single file. If a "file.json" is present in this cache directory, the file.json file should be loaded.
All these constructors should return a file cache instance that is a reference to any other file cache object for that archive that is already in memory. Consider a FileCacheFactory for this.
-
When calling addFile, rather than copying the file into the cache directory, the File Cache might just keep a pointer to the original location. This would require another function that explicitly copies all files into the cache directory.
-
Maintain a record of what files have changed since the last time the entity was stored. Also might keep a record of what files were changed since the last time file were aggregated to the cache directory.
-
When doing file manipulations, cache a copy of the file metadata to the disk. The presence of this file will indicate that changes have been made that have not been persisted to Synapse. This cached metadata should be deleted when storeEntity or load/downloadEntity are called.
A read-only file cache should be implemented that prevents the user from making changes to the cached files.
The behavior of the File Cache should be modified if the host system does not have zip installed. In these situations, the FileCache should only allow the user to add a single file to the cache. If the user attempts to add a second file when zip is not installed, the addFile method should throw an exception.
If zip is not installed, getArchiveFileMetadata() should return the single file contained in the file cache.
The property store works similarly to the Global Variable store with a couple key differences:
-
The data types of the values have strictly limited types that must map to the data types allowed by Synapse.
-
Rather than being global, the property store will be used to maintain properties for a single entity instance and will maintain pass-by-copy semantics.
At a minimum, the property store should implement the following methods:
-
addProperty(name, value) - add a property
-
deleteProperty(name) - delete the property
-
getProperty(name) - get the value associated with the property.
addProperty should be implemented in such a way that the return value of getProperty has the same data type as it had in it's call to addProperty.
Subclasses of the property store can be used to customize the behavior, enabling it to be used for both synapse properties and annotations.
The Property tore should have a method to convert the R object into the JSON format expected by Synapse. Similarly, the Property Store should have a constructor that can populate the object from JSON.
Location owners are "Locationable" and can be implemented using a FileCache. LocationOwners should hold an environment into which objects can be placed by the loadEntity function.
A read-only LocationOwner is a Location owner, with all of the content creation functions related to files disabled. Attributes and properties ReadOnlyLocationOwners are not necessarily read only.