~michaelforrest/use-case-mapper/trunk

# Because +after_find+ and +after_initialize+ are called for each object found and instantiated by a finder, such as <tt>Base.find(:all)</tt>, we've had

186

# to implement a simple performance constraint (50% more speed on a simple test case). Unlike all the other callbacks, +after_find+ and

187

# +after_initialize+ will only be run if an explicit implementation is defined (<tt>def after_find</tt>). In that case, all of the

188

# callback types will be called.

189

190

# == <tt>before_validation*</tt> returning statements

191

192

# If the returning value of a +before_validation+ callback can be evaluated to +false+, the process will be aborted and <tt>Base#save</tt> will return +false+.

193

# If Base#save! is called it will raise a ActiveRecord::RecordInvalid exception.

194

# Nothing will be appended to the errors object.

195

196

# == Canceling callbacks

197

198

# If a <tt>before_*</tt> callback returns +false+, all the later callbacks and the associated action are cancelled. If an <tt>after_*</tt> callback returns

199

# +false+, all the later callbacks are cancelled. Callbacks are generally run in the order they are defined, with the exception of callbacks

200

# defined as methods on the model, which are called last.

201

202

# == Transactions

203

204

# The entire callback chain of a +save+, <tt>save!</tt>, or +destroy+ call runs

205

# within a transaction. That includes <tt>after_*</tt> hooks. If everything

206

# goes fine a COMMIT is executed once the chain has been completed.

207

208

# If a <tt>before_*</tt> callback cancels the action a ROLLBACK is issued. You

209

# can also trigger a ROLLBACK raising an exception in any of the callbacks,

210

# including <tt>after_*</tt> hooks. Note, however, that in that case the client

211

# needs to be aware of it because an ordinary +save+ will raise such exception

212

# instead of quietly returning +false+.

213

module Callbacks

214

CALLBACKS = %w(

215

after_find after_initialize before_save after_save before_create after_create before_update after_update before_validation

216

after_validation before_validation_on_create after_validation_on_create before_validation_on_update

217

after_validation_on_update before_destroy after_destroy

218

)

219

220

def self.included(base) #:nodoc:

221

base.extend Observable

222

223

[:create_or_update, :valid?, :create, :update, :destroy].each do |method|

224

base.send :alias_method_chain, method, :callbacks

225

end

226

227

base.send :include, ActiveSupport::Callbacks

228

base.define_callbacks *CALLBACKS

229

end

230

231

# Is called when the object was instantiated by one of the finders, like <tt>Base.find</tt>.

232

#def after_find() end

233

234

# Is called after the object has been instantiated by a call to <tt>Base.new</tt>.

235

#def after_initialize() end

236

237

# Is called _before_ <tt>Base.save</tt> (regardless of whether it's a +create+ or +update+ save).

238

def before_save() end

239

240

# Is called _after_ <tt>Base.save</tt> (regardless of whether it's a +create+ or +update+ save).

241

# Note that this callback is still wrapped in the transaction around +save+. For example, if you

242

# invoke an external indexer at this point it won't see the changes in the database.

243

244

# class Contact < ActiveRecord::Base

245

# after_save { logger.info( 'New contact saved!' ) }

246

# end

247

def after_save() end

248

def create_or_update_with_callbacks #:nodoc:

249

return false if callback(:before_save) == false

250

if result = create_or_update_without_callbacks

251

callback(:after_save)

252

end

253

result

254

end

255

private :create_or_update_with_callbacks

256

257

# Is called _before_ <tt>Base.save</tt> on new objects that haven't been saved yet (no record exists).

258

def before_create() end

259

260

# Is called _after_ <tt>Base.save</tt> on new objects that haven't been saved yet (no record exists).

261

# Note that this callback is still wrapped in the transaction around +save+. For example, if you

262

# invoke an external indexer at this point it won't see the changes in the database.

263

def after_create() end

264

def create_with_callbacks #:nodoc:

265

return false if callback(:before_create) == false

266

result = create_without_callbacks

267

callback(:after_create)

268

result

269

end

270

private :create_with_callbacks

271

272

# Is called _before_ <tt>Base.save</tt> on existing objects that have a record.

273

def before_update() end

274

275

# Is called _after_ <tt>Base.save</tt> on existing objects that have a record.

276

# Note that this callback is still wrapped in the transaction around +save+. For example, if you

277

# invoke an external indexer at this point it won't see the changes in the database.

278

def after_update() end

279

280

def update_with_callbacks(*args) #:nodoc:

281

return false if callback(:before_update) == false

282

result = update_without_callbacks(*args)

283

callback(:after_update)

284

result

285

end

286

private :update_with_callbacks

287

288

# Is called _before_ <tt>Validations.validate</tt> (which is part of the <tt>Base.save</tt> call).

289

def before_validation() end

290

291

# Is called _after_ <tt>Validations.validate</tt> (which is part of the <tt>Base.save</tt> call).

292

def after_validation() end

293

294

# Is called _before_ <tt>Validations.validate</tt> (which is part of the <tt>Base.save</tt> call) on new objects

295

# that haven't been saved yet (no record exists).

296

def before_validation_on_create() end

297

298

# Is called _after_ <tt>Validations.validate</tt> (which is part of the <tt>Base.save</tt> call) on new objects

299

# that haven't been saved yet (no record exists).

300

def after_validation_on_create() end

301

302

# Is called _before_ <tt>Validations.validate</tt> (which is part of the <tt>Base.save</tt> call) on

303

# existing objects that have a record.

304

def before_validation_on_update() end

305

306

# Is called _after_ <tt>Validations.validate</tt> (which is part of the <tt>Base.save</tt> call) on

307

# existing objects that have a record.

308

def after_validation_on_update() end

309

310

def valid_with_callbacks? #:nodoc:

311

return false if callback(:before_validation) == false

312

if new_record? then result = callback(:before_validation_on_create) else result = callback(:before_validation_on_update) end

313

return false if false == result

314

315

result = valid_without_callbacks?

316

317

callback(:after_validation)

318

if new_record? then callback(:after_validation_on_create) else callback(:after_validation_on_update) end

319

320

return result

321

end

322

323

# Is called _before_ <tt>Base.destroy</tt>.

324

325

# Note: If you need to _destroy_ or _nullify_ associated records first,

326

# use the <tt>:dependent</tt> option on your associations.

327

def before_destroy() end

328

329

# Is called _after_ <tt>Base.destroy</tt> (and all the attributes have been frozen).

330

331

# class Contact < ActiveRecord::Base

332

# after_destroy { |record| logger.info( "Contact #{record.id} was destroyed." ) }

333

# end

334

def after_destroy() end

335

def destroy_with_callbacks #:nodoc:

336

return false if callback(:before_destroy) == false

337

result = destroy_without_callbacks

338

callback(:after_destroy)

339

result

340

end

341

342

private

343

def callback(method)

344

result = run_callbacks(method) { |result, object| false == result }

345

346

if result != false && respond_to_without_attributes?(method)

347

result = send(method)

348

end

349

350

notify(method)

351

352

return result

353

end

354

355

def notify(method) #:nodoc:

356

self.class.changed

357

self.class.notify_observers(method, self)

358

end

359

end

360

end

Older »