Allow Migration class code to detect an update vs fresh import of a row

Problem

When executing a migration, there are cases where code should only be executed the first time a row is migrated. Especially in the extra methods like prepare() and complete(). For example, Commerce Migrate Ubercart attaches a line item entity to its order in a complete() function. This works great the first time around, but will causes problems when an update is run.

Reason

migration.inc always sets $needsUpdate to STATUS_IMPORTED (which is 0):

  /**
   * Specify value of needs_update for current map row. Usually set by
   * MigrateFieldHandler implementations.
   *
   * @var int
   */
  public $needsUpdate = MigrateMap::STATUS_IMPORTED;

Proposed Solution

Set $needsUpdate at a later time and reflect the actual status of the row being imported.

I've been doing this via a db_query() on the relevant migrate_map table to get the actual value from the needs_update column for this row. If it's STATUS_NEEDS_UPDATE, then I set an $update flag to TRUE and go from there. I'm sure there must be a more elegant way to accomplish this.

$update = db_query('SELECT needs_update FROM {migrate_map_foo} WHERE sourceid1 = :id AND needs_update = :flag', array(':id' => $row->nid, ':flag' => MigrateMap::STATUS_NEEDS_UPDATE));

I suppose we can add something like this to Migrate::__construct().

Notes

While the comment states "Usually set by MigrateFieldHandler implementations." I can't actually find any use of this property in plugins/destinations/fields.inc.