added description about flushing and transaction to documentation

Author: Yasuharu NAKANO

src/docs/guide/optimisticLocking.gdoc

@@ -20,6 +20,8 @@ sampleDomain.withOptimisticLocking(modificationBaseVersion) { Object domain ->
 }
 {code}
 
+See also [Optimistic and Pessimistic locking|http://grails.org/doc/latest/guide/single.html#locking].
+
 
 h3. Type of modificationBaseVersion
 
@@ -88,3 +90,19 @@ In case of conflict, a return value of @onConflict@'s closure is returned.
 {code}
 assert result.returnValue == "NG"
 {code}
+
+
+h3. Flushing session
+
+In case of using persistence methods (e.g. @save@ method), you must be flush a session.
+
+{code}
+def result = sampleDomain.withOptimisticLocking(modificationBaseVersion) { Object domain ->
+    domain.save(flush: true)
+}.onConflict { Object domain, Throwable caused ->
+    return "NG" // In case of error, you can catch and handle it here.
+}
+{code}
+
+Otherwise, a conflict error occurs on flushing at outside of controller action and you cannot handle the error.
+Instead, you will see the 500 error page at development mode.

src/docs/guide/pessimisticLocking.gdoc

@@ -9,12 +9,14 @@ SampleDomain.withPessimisticLock(id) { Object lockedDomain ->
 
     // operation to require a pessimistic lock
 
-}.onNotFound { ->
+}.onNotFound {domainId ->
 
     // operation when the target is not found
 }
 {code}
 
+See also [Optimistic and Pessimistic locking|http://grails.org/doc/latest/guide/single.html#locking] and [lock method|http://grails.org/doc/latest/ref/Domain%20Classes/lock.html] of domain class.
+
 
 h3. onNotFound is optional
 
@@ -31,15 +33,23 @@ In this case, when target isn't found, all the plugin has to do is nothing.
 
 h3. Closure arguments
 
-The @lockedDomain@ argument of @onNotFound@'s closure is the domain instance which is found by @SampleDomain.lock(id)@ method.
+The @lockedDomain@ argument of @withPessimisticLock@'s closure is the domain instance which is found by @SampleDomain.lock(id)@ method.
 
 {code}
 SampleDomain.withPessimisticLock(id) { Object lockedDomain ->
     assert lockedDomain.id == id
 }
 {code}
 
-There are no argument for @onNotFound@'s closure.
+The domainId argument of @onNotFound@'s closure is the domain id which is specified to @withPessimisticLock@'s first argument.
+
+{code}
+SampleDomain.withPessimisticLock(id) { Object lockedDomain ->
+    // ...
+}.onNotFound {domainId ->
+    assert domainId == id
+}
+{code}
 
 
 h3. Return value
@@ -59,3 +69,10 @@ In case that no row is found, a return value of @onNotFound@'s closure is return
 {code}
 assert result.returnValue == "NG"
 {code}
+
+
+h3. Transaction is required
+
+When you want to use a pessimistic lock, you must need a transaction.
+The aquired lock is automatically released when the transaction commits.
+