From a6224165e0046ff4e44f978a5c4211e289728ea2 Mon Sep 17 00:00:00 2001 From: Mattias Arthursson Date: Mon, 5 Mar 2007 18:33:52 +0000 Subject: [PATCH] Finalized transaction documentation. --- .../docs/reference/src/transactions.xml | 87 ++++++++++++++----- 1 file changed, 65 insertions(+), 22 deletions(-) diff --git a/spring-ldap/docs/reference/src/transactions.xml b/spring-ldap/docs/reference/src/transactions.xml index 90841568..9249817a 100644 --- a/spring-ldap/docs/reference/src/transactions.xml +++ b/spring-ldap/docs/reference/src/transactions.xml @@ -1,7 +1,7 @@ - Spring LDAP Transaction Support + Transaction Support Introduction @@ -9,27 +9,32 @@ 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. - + Recognizing that this may be 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. - + restore the initial state should the transaction need to be rolled back. 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. + allowing for more efficient resources usage. + + It is important to note that while the approach used by Spring LDAP to provide transaction support + 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 this 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. + The client side transaction support will add some overhead in addition to the work required + by the original operations. While this overhead should not be something to worry about in most cases, + if your application will not perform several LDAP operations within the same + transaction (e.g. a modifyAttributes followed by a rebind), or + if transaction synchronization with a JDBC data source is not required (see below) there will be nothing to gain + by using the LDAP transaction support. + @@ -86,8 +91,25 @@ around the targets; contextSource and myDataAccessObject - - LDAP Compensating Transactions + + JDBC Transaction Integration + A common use case when working against LDAP is that some of the data is stored in the LDAP tree, but + other data is stored in a relational database. In this case, transaction support becomes even more important, + since the update of the different resources should be synchronized. + While actual XA transactions is not supported, support is provided to conceptually wrap JDBC and LDAP + access within the same transaction using the ContextSourceAndDataSourceTransactionManager. + A DataSource and a ContextSource is supplied to the + ContextSourceAndDataSourceTransactionManager, which will then manage the two transactions, + virtually as if they were one. When performing a commit, the LDAP part of the operation will always + be performed first, allowing both transactions to be rolled back should the LDAP commit fail. The JDBC + part of the transaction is managed exactly as in DataSourceTransactionManager, except that + nested transactions is not supported. + Once again it should be noted that the provided support is all client side. The wrapped transaction is not + an XA transaction. No two-phase as such commit is performed, as the LDAP server will be unable to vote on its outcome. + Once again, however, for the majority of cases the supplied support will be sufficient. + + + LDAP Compensating Transactions Explained 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). @@ -119,28 +141,28 @@ - Bind + bind Make record of the DN of the entry to bind. Bind the entry. No operation. Unbind the entry using the recorded DN. - Rename + rename Make record of the original and target DN. Rename the entry. No operation. Rename the entry back to its original DN. - Unbind + 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 + 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 @@ -148,7 +170,7 @@ Rename the entry from the temporary location back to its original DN. - ModifyAttributes + 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. @@ -161,5 +183,26 @@ A more detailed description of the internal workings of the Spring LDAP transaction support is available in the javadocs. - + + Renaming Strategies + As described in the table above, the transaction management of some operations require the original entry affected + by the operation to be temporarily renamed before the actual modification can be made in the commit. + The manner in which the temporary DN of the entry is calculated is managed by a TempEntryRenamingStrategy + supplied to the ContextSourceTransactionManager. Two implementations are supplied with Spring LDAP, + but if specific behaviour is required a custom implementation can easily be implemented by the user. The + provided TempEntryRenamingStrategy implementations are: + + DefaultTempEntryRenamingStrategy (the default). Adds a suffix to the least significant + part of the entry DN. E.g. for the DN cn=john doe, ou=users, this strategy would return the + temporary DN cn=john doe_temp, ou=users. The suffix is configurable using the tempSuffix + property + DifferentSubtreeTempEntryRenamingStrategy. Takes the least significant part of the DN + and appends a subtree DN to this. This makes all temporary entries be placed at a specific location in the LDAP tree. + The temporary subtree DN is configured using the subtreeNode property. E.g., if + subtreeNode is ou=tempEntries and the original DN of the entry is + cn=john doe, ou=users, the temporary DN will be cn=john doe, ou=tempEntries. + Note that the configured subtree node needs to be present in the LDAP tree. + + + \ No newline at end of file