From 56ef29a640b881c3d4fa00ae1b4e15f0273bacc0 Mon Sep 17 00:00:00 2001 From: Mattias Arthursson Date: Sun, 4 Mar 2007 16:13:55 +0000 Subject: [PATCH] Continued documentation of transaction support. --- .../docs/reference/src/transactions.xml | 96 +++++++++++++++---- 1 file changed, 80 insertions(+), 16 deletions(-) diff --git a/spring-ldap/docs/reference/src/transactions.xml b/spring-ldap/docs/reference/src/transactions.xml index 1423060b..90841568 100644 --- a/spring-ldap/docs/reference/src/transactions.xml +++ b/spring-ldap/docs/reference/src/transactions.xml @@ -1,7 +1,7 @@ - LDAP Transaction Support + Spring LDAP Transaction Support Introduction @@ -26,6 +26,10 @@ that the alternative will be to operate without any transaction support whatsoever; this is pretty much as good as it gets. + In addition to the actual transaction management, Spring LDAP transaction support also + makes sure that the same DirContext instance will be used throughout the same transaction, + i.e. the DirContext will not actually be closed until the transaction is finished, + allowing for more efficient usage of resources. @@ -82,20 +86,80 @@ around the targets; contextSource and myDataAccessObject - - The Inner Workings - In order to properly benefit from the Spring LDAP transaction support it will be useful to know - something about the inner workings. At the heart of the LDAP transaction support, of course, there - is the ContextSourceTransactionManager. This works in close collaboration with - a CompensatingTransactionOperationManager instance, which is tied to the transaction - by the TransactionManager. Using the TransactionAwareContextSourceProxy causes - all modifying operations to be forwarded to the CompensatingTransactionOperationManager, - which "records" the state before the operation and gets a CompensatingTransactionOperationExecutor - for the specific operation. One OperationExecutor is responsible for executing and committing or rolling back - one single operation, and OperationManager manages a sequence of OperationExecutors representing all operations - within a transaction. - Now, the CompensatingTransactionOperationExecutor knows the relevant state before the operation - was performed. - + + LDAP Compensating Transactions + Spring LDAP manages compensating transactions by making record of the state in the LDAP tree + before each modifying operation (bind, unbind, rebind, + modifyAttributes, and rename). + This enables the system + to perform compensating operations should the transaction need to be rolled back. In many cases the + compensating operation is pretty straightforward. E.g. the compensating rollback operation for a + bind operation will quite obviously be to unbind the entry. Other operations however require + a different, more complicated approach because of some particular characteristics of LDAP databases. Specifically, + it is not always possible to get the values of all Attributes of an entry, making the above + strategy insufficient for e.g. an unbind operation. + This is why each modifying operation performed within a Spring LDAP managed transaction is internally + split up in four distinct operations - a recording operation, a preparation operation, a commit operation, + and a rollback operation. The specifics for each LDAP operation is described in the table below: + + + + + + + + + + LDAP Operation + Recording + Preparation + Commit + Rollback + + + + + Bind + Make record of the DN of the entry to bind. + Bind the entry. + No operation. + Unbind the entry using the recorded DN. + + + Rename + Make record of the original and target DN. + Rename the entry. + No operation. + Rename the entry back to its original DN. + + + Unbind + Make record of the original DN and calculate a temporary DN. + Rename the entry to the temporary location. + Unbind the temporary entry. + Rename the entry from the temporary location back to its original DN. + + + Rebind + Make record of the original DN and the new Attributes, and calculate a temporary DN. + Rename the entry to a temporary location. + Bind the new Attributes at the original DN, and unbind the original entry + from its temporary location. + Rename the entry from the temporary location back to its original DN. + + + ModifyAttributes + Make record of the DN of the entry to modify and calculate compensating ModificationItems + for the modifications to be done. + Perform the modifyAttributes operation. + No operation. + Perform a modifyAttributes operation using the calculated compensating + ModificationItems. + + + +
+ A more detailed description of the internal workings of the Spring LDAP transaction support is available in the + javadocs. \ No newline at end of file