This is the specification of the command sets for Synapse clients. The goal is to align the command sets for clients in different languages to ease users' transitions between languages. Additionally we define the organization of the file cache so that various clients arrange local copies of file consistently.
| Command | comments | R Syntax | Python Syntax | Command Line Syntax |
|---|---|---|---|---|
| 1 – Basic Level | ||||
| Create a Synapse file handle in memory, specifying the path to the file in the local file system, the name in Synapse, and the Folder in Synapse. This step 'stages' a file to be sent to Synapse. | The specified file doesn't move or get copied at this time. | File(path="/path/to/file", name="foo", parentId="syn101") | ||
| Create a Synapse file handle in memory which will be a serialized version of an in-memory object. | The object is not serialized at this time. (We are hoping people will like calling the object a File, even though it takes an in-memory object as a parameter.) | File(obj=<obj ref>, name="foo", parentId="syn101") | ||
| TODO: File which is a URL, not be uploaded to Synapse, just linked. | ||||
| Create a Synapse Record in memory, specifying the paths to one or more files in the local file system, the name in Synapse, and the Folder in Synapse. This step 'stages' a Record to be sent to Synapse. | Files aren't moved or copied at this time. TODO: Should the files instead be set like attributes, using synSet()? | Record(paths=list("path1", "path2"), name="foo", parentId="syn101") | Record(paths=list("path1", "path2"), name="foo", parentId="syn101") | |
| Create a Folder or Project in memory. | Folder(name="foo", parentId="syn101") Project(name="foo", parentId="syn101") | |||
| Set an entity's attribute (property or annotation) in memory. Client first checks properties, then goes to annotations; setting to NULL deletes it | synSet(entity, name)<-value | |||
| Gets an entity's attribute value (property or annotation) from the object already in memory. If value is not set then NULL is returned. | (TODO: Do we need an isSet(entity, name) method?) | synGetAnnotationOrProperty(entity, name) (We obviously need a better name here.) | ||
| Create or update an entity (File, Folder, etc.) in Synapse. May also specify (1) whether a name collision in an attempted 'create' should become an 'update' and (2) whether to 'force' a new version to be created. | synStore(entity, createOrUpdate=T, forceVersion=T) | |||
| Get an entity (file, folder, etc.) from the Synapse server, with its attributes (properties, annotations) and, optionally, with its associated file(s). | synGet(id, version, downloadFile=T, load=T) | synapse.get(id, version, downloadFile=True, load=True) | synapse get ID -v NUMBER | |
| synGet(entity, downloadFile=T, load=T) | ||||
| Add a file to a Record entity | TODO: Can this be combined with synSet(record, ...)? | synAdd(record)<-"path/to/file" | ||
| 2 – Power User Level | ||||
| we talked about this, but is it needed? | synGetEntity() | |||
| we talked about this, but is it needed? | synStoreEntity() | |||
| Retrieve the wiki for an entity | TODO: Is it a requirement that we retrieve attachments? If not, do we retrieve file handles? | synGetWiki(id, version) / synGetWiki(entity) | ||
| synStoreWiki() | ||||
| synGetAnnotations() | ||||
| synStoreAnnotations() | ||||
| synGetProperties() | ||||
| synSetProperties() | ||||
| synGetAnnotation() | ||||
| synStoreAnnotation() | ||||
| TODO: 'mark dirty' A client command to mark a file associated with an entity as having been modified locally. | ||||
| 3 – Web API Level | ||||
| Execute GET request | synRestGET(endpoint, uri) | |||
| Execute POST request | synRestPOST(endpoint, uri, body) | |||
| Execute PUT request | synRestPUT(endpoint, uri, body) | |||
| Execute DELETE request | synRestDELETE(endpoint, uri) |
Cache Design Principles
The function and design principles of the client-side file cache need to be made explicit. The options are below.
Option 1: The Download Cache
The client has a file cache on the local file system. When an File or Record entity is fetched, if its associated files are fetched then they go into the cache.
The files in the cache may be modified. That is, the client may not assume that a file in the cache is identical to the one in Synapse.
There is no requirement that the local file associated with an entity be in the cache. That is, the entity must hold a reference to the local file handle, without assuming its location.
Files may be deleted from the cache by the client at any time.
TODO: How do we support caching in between sessions? Is it a valid use case to use the cache as a mirror, or is that a misuse of its function?
Option 2: The lazy mirror
The client has a file cache on the local file system. When an File or Record entity is fetched, if its associated files are fetched then they go into the cache.
When an entity is stored, any associated files are moved into the cache immediately.
The location of a cached file can always be derived from entity meta data. E.g. the entity id and file name may be used to construct the location file handle.
The cache may not be modified by the client except in the course of doing entity CRUD in Synapse. In particular, the cache is not a 'scratch' space. (Is this requirement really needed?)