Obj-C API 2: DBFILESWriteMode - using -initWithUpdate with file revs vs -initWithOverwrite:

[Keith B.7]

In API 1, to overwite an existing file on the server, it was always necessary (as I understand it) to provide the file rev of the existing file. If you didn't do this, you would receive an error. Otherwise, you had to first delete the file and then write it again. (I could be wrong about this - maybe it was possible to overwrite a file without a rev but I just never did it.)

In API 2, DBFILESWriteMode allows you to determine what will happen if a file already exists at the chosen path when trying to upload a file. You have three choices:

a. Update: requires the file rev. If the file rev is not provided or does not match, it will be treated as a conflict.

b. Overwrite: always overwrites the file at the given location no matter what.

c. Add: always creates a conflicted file if a file exists at the given location (opposite of (b)).

Two questions related to this:

1. If autorename is set to NO for the upload task, will (a) and (b) always result in an error if the file cannot be written at the selected path? (This is what I would expect: if I pass in NO for autorename, I would not expect the frameworks to create any file if it cannot be placed at the exact specified location.)

In API 1, when uploading with a file rev, if there was a "failed to grab file locks" error or if the rev was wrong, the file would still be uploaded but using a different (conflicted) file name, so that I had to check for that case and try to fix things up if it happened. So will passing YES for autorename result in the same behaviour as API 1, but passing NO avoid this issue entirely and *never* result in the uploaded file using a different name ("conflict" etc)?

2. Is there any advantage in using (a) over (b)? At the moment I am maintaining file revs and using them for uploads. Is there a good reason to continue with this approach rather than just forcing an overwrite every time I want to update an existing file?

Thanks,

Keith

[Greg-DB · Accepted solution]

Hi Keith, for reference, yes, in API v1 it was also possible to just overwrite a file without a rev. In either though, it's generally not reccomended, as its easy to overwrite data you didn't intend to due to race conditions that way.

1. That's correct, with autorename set to NO, the API won't attempt to find somewhere to put the file, and will just returned the conflict error. And correct, the YES behavior will successfully commit the file, just at a different path, like the API v1 behavior you describe.

2. Yes, we definitely recommend using update instead of overwrite, because of the potential of race conditions, as mentioned above. (E.g., if two instances of your app happen to upload new versions at about the same time, one will blow away the other version.)

[Keith B.7]

Great, thanks!