...
The analytical clients provide for client-side caching of Synapse files, to avoid unnecessarily retrieving (large or many) files that have already been downloaded. Downloaded files may be cached in one of two ways: (1) By default, downloaded files are put in a Read Only cache, organized by (MD5) hash. The organization is:
<cache root> / <hash prefix> / <hash>
where <cache root> is a folder whose location is configurable during client installation and whose default is within the user's home directory; <hash prefix> is the first two hex digits of the hash, and <hash> is the name used for the file, the full MD5 hash. The reason for using the intermediate <hash prefix> directory is to avoid having too many files in a single folder.
(2) Alternatively, the a file may be downloaded to a folder location specified by the user. The location must be outside of the Read Only cache. We call this this an an "external cache location". In this case the file may be modified.
the system default download folder (e.g. on the Macintosh it's ~/Downloads/). Alternatively, the a file may be downloaded to a folder location specified by the user. When synStore() is called to create an entity having a file in an external cache location, the local copy of the file is not moved. It serves as a "cached copy" in its current location, as described below.
When synGet() is called, the client first retrieves the File metadata, including the MD5 hash. If no download location is specified, then the client checks the default cache location. If the file is already there it is not The client forms the download location based on the cached location (default or specified by the user) and the file name. If a local copy of the file does not exist, it's downloaded again. If absent, the file is downloaded. If the download destination is an external cache locationpresent, the client computes the MD5 of the local copy to determine whether it differs from the version in Synapse. If so, the client must (based on user choice) either (1) create new, unique file name, (2) confirm overwrite or (3) keep the original file. (If the latter, a subsequent synStore() would overwrite the Synapse version with the local copy.)
When synStore() is called to update an entity, if the file location is the default, Read Only cache, then the file is not uploaded. If the file location is an external cache location, When synStore() is called to update an entity then the MD5 hash of the file is recomputed. The file is uploaded if and only if the newly computed MD5 hash differs from that of the previously retrieved entity.
The effect of this architecture is that repeated downloads are avoided:
...
hash differs from that of the previously retrieved entity.
The effect of this architecture is that repeated uploads or downloads of an entity's file
...
are avoided when the local copy is not modified.
...
This strategy does not avoid repeated downloads of an entity's file to a variety of local folders (e.g. to the default location and then to an external one, or to two different external ones). We feel that the potential efficiency gains of doing this are outweighed by the complexity of tracking multiple, mutable copies of a file.
...