Offer options on how to handle uri collisions

Here is the patch from
#1314748-7: Files need to be resaved on update.

Amazing, now this does actually work :)

Here is a very basic patch.

EDIT:
There is probably a lot of redundancy with other parts of code, where things are already being checked.

Also, the dedupe stuff that I talk about in the comments, needs to happen somewhere. This all depends how the $file objects are prefilled with uri etc, stuff that is happening before this function.
Honestly, I did not study any of this.

"needs review"

thanks :)

There is no confusion over what the primary key is - the point of searching for an existing uri is the presumption that a matching uri means the file in question already exists, and thus we want to point to it. [..] Your assumption is that it's a different file with the same name, so you want to dedupe it?

It could be a different file, which has nothing to do with our migration.
Or it could be the very same file, which we are now supposed to update.

The little difficulty I have is that I have not studied what happens before the import() method.
In the critical situation, we have a $file object with a not-NULL $file->fid, and a $file->uri which points to an already-existing file.
How is this uri determined? And what does it tell us? Please, copy the new file here? Or, the new file already has been copied here?
What is the intended behavior, if the import() method is called with such a $file object?

The critical thing happens here, where $file->fid is set to NULL. This will turn an update into an insert.
http://drupalcode.org/project/migrate.git/blob/refs/heads/7.x-2.x:/plugi...

Some situations where this can break:

Scenario 1)
Source has an id for each file and, of course, a filename, path or uri, associated with each file id.
Our custom migration class has some conversion logic, to suggest a filename and path for the migrated file.
Finally, the file gets a destination fid, and a uri.

This all works great for the first import.
migrate_map_userpic is now filled with mappings between destination fid and source file id.

Now, second time import with --update.
In the meantime, some of the files in the source system have been renamed or moved around. Also, the logic to suggest a new filename for each migrated file, has changed.

Looking files with the same uri fails, because the uri is not the same as in the first import.
The evil $file->fid = NULL happens, and what should be an UPDATE is turned into an INSERT.

Intended behavior would be to delete the previously migrated files, but keep the respective records in file_managed, and then copy the original files to the new location.

Scenario 2)
Similar to the above, but now we create stub files.
We need this for user pictures.

The stub files are are just stupid blank txt files, that we create in a location where it doesn't hurt.

The second time we want to update these files to something real. But again, the uri check fails, and turns the UPDATE into an INSERT on file_managed.

The intended behavior would be to delete the stub file, keep the record in file_managed, copy the source file to the new destination uri location.

-------

So, the lesson learned:
If $file->fid is not NULL, then we want to update, not insert. If the $file->uri looks like something new, this is probably because the original file has been renamed, or there are other reasons why we want to save the file in a different path.

Question is, at which point in the pipeline should this be dealt with?