Drupal 7 Module Development

Working with Content
}
catch (Exception $e) {
$transaction->rollback();
watchdog_exception('artwork', $e, NULL, WATCHDOG_ERROR);
return FALSE;
}
Most of the save routine is self-explanatory, and much of it is specific to the properties
we've declared on our entity. A few parts bear further discussion, however.
We're wrapping the entire process in a PHP try-catch block. That's because the
save process could be arbitrarily complex, involving a number of queries, any of
which could, potentially, break. We therefore start a database transaction with the
db_transaction() function. Transactions allow multiple database queries to either
all succeed or all fail together. Any queries that run, from anywhere, between the
db_transaction() call and when the $transaction variable goes out of scope at
the end of the function will be part of that transaction.
If any queries, anywhere, fail, the database will throw an Exception. (There are
other reasons an Exception could be thrown, too, but that is the most common.)
In that case, we roll back the entire transaction with the rollback() method. Any
queries that had already run get undone, and the entire save process effectively does
not happen. That keeps us from ending up with a half-saved artwork, which requires
manually editing the database to clean up. We also log the exception using a special
utility function that decodes useful information from the exception for us.
Note that transactions are not available if using MySQL's
MyISAM database tables. In that case code will still function but
any attempt to roll back a transaction will be ignored and the
database will still be left in a potentially unstable state. For that
reason, when running on MySQL Drupal defaults to InnoDB
tables, which support transactions.
Once we're done saving the artwork, we also call db_ignore_slave(). If we're
running a high-traffic site then we may have both a master database and one or more
slave databases configured, something Drupal supports natively. However, there
may be a latency before our artwork gets propagated from the master server to the
slave server. We therefore tell Drupal that, for the current user only, it should skip
the slave server for a few minutes so that the user that submitted the artwork will
see it immediately, even if there is a brief delay for other users.
[ 174 ]