From 8cc110e8578bead52e5d31faeac9ea1e70de7ae6 Mon Sep 17 00:00:00 2001 From: Mattias Arthursson Date: Tue, 27 Feb 2007 19:43:55 +0000 Subject: [PATCH] Started documentation of transactions. --- spring-ldap/docs/reference/src/index.xml | 2 + .../docs/reference/src/transactions.xml | 101 ++++++++++++++++++ 2 files changed, 103 insertions(+) create mode 100644 spring-ldap/docs/reference/src/transactions.xml diff --git a/spring-ldap/docs/reference/src/index.xml b/spring-ldap/docs/reference/src/index.xml index 0669e9a8..0cf2332f 100644 --- a/spring-ldap/docs/reference/src/index.xml +++ b/spring-ldap/docs/reference/src/index.xml @@ -8,6 +8,7 @@ + ]> @@ -45,6 +46,7 @@ &overview; &basic; &dirobjectfactory; + &transactions; &executors; &contextprocessor; &configuration; diff --git a/spring-ldap/docs/reference/src/transactions.xml b/spring-ldap/docs/reference/src/transactions.xml new file mode 100644 index 00000000..1423060b --- /dev/null +++ b/spring-ldap/docs/reference/src/transactions.xml @@ -0,0 +1,101 @@ + + + + LDAP Transaction Support + + + Introduction + + Programmers used to working with relational databases coming to the LDAP + world often express surprise to the fact that there is no notion of transactions. + It is not specified in the protocol, and thus no servers support it. + Recognizing that this is a major problem, Spring LDAP provides support for client-side, + compensating transactions on LDAP resources. + + + LDAP transaction support is provided by ContextSourceTransactionManager, a + PlatformTransactionManager implementation that manages Spring transaction + support for LDAP operations. Along with its collaborators it keeps track of the LDAP operations + performed in a transaction, making record of the state before each operation and taking steps to + restore the initial state should the transaction need to be rolled back. + + It is important to note that while the above approach is sufficient for many cases, + it is by no means "real" transactions in the traditional sense. The server is completely + unaware of the transactions, so e.g. if the connection is broken there will be no hope to rollback + the transaction. While the above should be carefully considered it should also be noted + that the alternative will be to operate without any transaction support whatsoever; this is pretty much + as good as it gets. + + + + + Configuration + + Configuring Spring LDAP transactions should look very familiar if you're used to configuring Spring transactions. + You will create a TransactionManager instance and wrap your target object using a + TransactionProxyFactoryBean. In addition to this, you will also need to wrap your + ContextSource in a TransactionAwareContextSourceProxy. + + <beans> + ... + <bean id="contextSourceTarget" class="org.springframework.ldap.core.support.LdapContextSource"> + <property name="url" value="ldap://localhost:389" /> + <property name="base" value="dc=example,dc=com" /> + <property name="userDn" value="cn=Manager" /> + <property name="password" value="secret" /> + </bean> + + <bean id="contextSource" + class="org.springframework.ldap.transaction.core.TransactionAwareContextSourceProxy"> + <constructor-arg ref="contextSourceTarget" /> + </bean> + + <bean id="ldapTemplate" class="org.springframework.ldap.core.LdapTemplate"> + <constructor-arg ref="contextSource" /> + </bean> + + <bean id="transactionManager" + class="org.springframework.ldap.transaction.core.ContextSourceTransactionManager"> + <constructor-arg ref="contextSource" /> + </bean> + + <bean id="myDataAccessObjectTarget" class="com.example.MyDataAccessObject"> + <property name="ldapTemplate" ref="ldapTemplate" /> + </bean> + + <bean id="myDataAccessObject" + class="org.springframework.transaction.interceptor.TransactionProxyFactoryBean"> + <property name="transactionManager" ref="transactionManager" /> + <property name="target" ref="myDataAccessObjectTarget" /> + <property name="transactionAttributes"> + <props> + <prop key="*">PROPAGATION_REQUIRES_NEW</prop> + </props> + </property> + </bean> + ... + + In a real world example you would probably apply the transactions on the service object level + rather than the DAO level; the above serves as an example to demonstrate the general idea. + You'll notice that the actual ContextSource and DAO instances get ids with a + "Target" suffix. The beans you will actually refer to are the Proxies that are created + 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. + + + \ No newline at end of file