Local Synapse Cache

When the R client retrieves information from Synapse for use in the R session, it creates a local disk copy of the retrieved information. This provides (1) efficient performance when repeated references are made to the same remote information, (2) support for off-line operation. When putting data in the local file cache we avoid imposing a language-specific representation. (In particular we avoid using an R-binary representation.) This allows access to a common cache by clients written in a variety of languages. Metadata is stored in a simple JavaScript Object Notation (JSON) format.

##The Synapse cache is structured as follows:
Default root directory: ~/.synapseCache (Note: this is configurable.)
Folder for entity metadata: < root dir >/<synapse endpoint>/<entity url> /.
Example: ~/.synapseCache/synapse.sagebase.org/repo/v1/entity/101/
(Note: Using the Synapse endpoint rather than only the entity URI allows a single R client to work with multiple Synapse stacks.)
Folder for URL referenced files: < root dir >/file/< host >/< path >, where < host > and < path > are taken from the URL.
Example: ~/.synapseCache/file/ftp.ncbi.nih.gov/pub/geo/DATA/supplementary/series/GSE21539/GSE21539_RAW.tar

##Within the entity metadata folder there are:

1. A file for the basic entity metadata, called entity.json.
   Example: ~/.synapseCache/entity/101/entity.json
2. A file for the entity's extended annotations, called annotations.json.
   Example: ~/.synapseCache/entity/101/annotations.json
3. Subfolder(s) for specific versions of the entity, each with files for the versions' metadata.
   Example: For version 1 of an entity, ~/.synapseCache/entity/101/1/entity.json

The metadata files contain a variety of URL references, e.g. a location of a Data object, or an Attachment. Local copies of all such references are saved under <root dir>/file/.

##Within the folder for URL referenced files there are:

1. A directory into which the contents of the archive are unpacked. This directory is named according to the convention: _unpacked.

Example: ~/.synapseCache/file/ftp.ncbi.nih.gov/pub/geo/DATA/supplementary/series/GSE21539/GSE21539_RAW.tar_unpacked/

2. A json file containing the metadata about the files contained in the archive:

Example: ~/.synapseCache/file/ftp.ncbi.nih.gov/pub/geo/DATA/supplementary/series/GSE21539/file.json