0
@@ -83,8 +83,33 @@ module ActiveRecord #:nodoc:
0
   class ReadOnlyRecord < ActiveRecordError
0
   end
0
 
0
-  # Used by Active Record transaction mechanism to distinguish rollback from other exceptional situations.
0
-  # You can use it to roll your transaction back explicitly in the block passed to +transaction+ method.
0
+  # ActiveRecord::Transactions::ClassMethods.transaction uses this exception
0
+  # to distinguish a deliberate rollback from other exceptional situations.
0
+  # Normally, raising an exception will cause the +transaction+ method to rollback
0
+  # the database transaction *and* pass on the exception. But if you raise an
0
+  # ActiveRecord::Rollback exception, then the database transaction will be rolled back,
0
+  # without passing on the exception.
0
+  #
0
+  # For example, you could do this in your controller to rollback a transaction:
0
+  #
0
+  #   class BooksController < ActionController::Base
0
+  #     def create
0
+  #       Book.transaction do
0
+  #         book = Book.new(params[:book])
0
+  #         book.save!
0
+  #         if today_is_friday?
0
+  #           # The system must fail on Friday so that our support department
0
+  #           # won't be out of job. We silently rollback this transaction
0
+  #           # without telling the user.
0
+  #           raise ActiveRecord::Rollback, "Call tech support!"
0
+  #         end
0
+  #       end
0
+  #       # ActiveRecord::Rollback is the only exception that won't be passed on
0
+  #       # by ActiveRecord::Base.transaction, so this line will still be reached
0
+  #       # even on Friday.
0
+  #       redirect_to root_url
0
+  #     end
0
+  #   end
0
   class Rollback < ActiveRecordError
0
   end
0