Reviewed javadoc.

spring-ldap/src/main/java/org/springframework/ldap/transaction/compensating/manager/ContextSourceAndDataSourceTransactionManager.java

@@ -27,9 +27,10 @@ import org.springframework.transaction.support.DefaultTransactionStatus;
  * A Transaction Manager to manage LDAP and JDBC operations within the same
  * transaction. Note that even though the same logical transaction is used, this
  * is <b>not</b> a JTA XA transaction; no two-phase commit will be performed,
- * and thus commit and rollback may result in unexpected results.
+ * and thus commit and rollback may yield unexpected results.
  * 
  * @author Mattias Arthursson
+ * @since 1.2
  */
 public class ContextSourceAndDataSourceTransactionManager extends
         DataSourceTransactionManager {
@@ -45,8 +46,6 @@ public class ContextSourceAndDataSourceTransactionManager extends
     }
 
     /*
-     * (non-Javadoc)
-     * 
      * @see org.springframework.jdbc.datasource.DataSourceTransactionManager#isExistingTransaction(java.lang.Object)
      */
     protected boolean isExistingTransaction(Object transaction) {
@@ -57,8 +56,6 @@ public class ContextSourceAndDataSourceTransactionManager extends
     }
 
     /*
-     * (non-Javadoc)
-     * 
      * @see org.springframework.jdbc.datasource.DataSourceTransactionManager#doGetTransaction()
      */
     protected Object doGetTransaction() throws TransactionException {
@@ -71,8 +68,6 @@ public class ContextSourceAndDataSourceTransactionManager extends
     }
 
     /*
-     * (non-Javadoc)
-     * 
      * @see org.springframework.jdbc.datasource.DataSourceTransactionManager#doBegin(java.lang.Object,
      *      org.springframework.transaction.TransactionDefinition)
      */
@@ -87,8 +82,6 @@ public class ContextSourceAndDataSourceTransactionManager extends
     }
 
     /*
-     * (non-Javadoc)
-     * 
      * @see org.springframework.jdbc.datasource.DataSourceTransactionManager#doCleanupAfterCompletion(java.lang.Object)
      */
     protected void doCleanupAfterCompletion(Object transaction) {
@@ -101,8 +94,6 @@ public class ContextSourceAndDataSourceTransactionManager extends
     }
 
     /*
-     * (non-Javadoc)
-     * 
      * @see org.springframework.jdbc.datasource.DataSourceTransactionManager#doCommit(org.springframework.transaction.support.DefaultTransactionStatus)
      */
     protected void doCommit(DefaultTransactionStatus status)
@@ -138,8 +129,6 @@ public class ContextSourceAndDataSourceTransactionManager extends
     }
 
     /*
-     * (non-Javadoc)
-     * 
      * @see org.springframework.jdbc.datasource.DataSourceTransactionManager#doRollback(org.springframework.transaction.support.DefaultTransactionStatus)
      */
     protected void doRollback(DefaultTransactionStatus status)
@@ -191,16 +180,23 @@ public class ContextSourceAndDataSourceTransactionManager extends
         }
     }
 
+    /*
+     * @see org.springframework.jdbc.datasource.DataSourceTransactionManager#doSuspend(java.lang.Object)
+     */
     protected Object doSuspend(Object transaction) throws TransactionException {
         throw new TransactionSuspensionNotSupportedException(
                 "Transaction manager [" + getClass().getName()
                         + "] does not support transaction suspension");
     }
 
+    /*
+     * @see org.springframework.jdbc.datasource.DataSourceTransactionManager#doResume(java.lang.Object,
+     *      java.lang.Object)
+     */
     protected void doResume(Object transaction, Object suspendedResources)
             throws TransactionException {
         throw new TransactionSuspensionNotSupportedException(
                 "Transaction manager [" + getClass().getName()
                         + "] does not support transaction suspension");
     }
-}
+}

spring-ldap/src/main/java/org/springframework/ldap/transaction/compensating/manager/ContextSourceTransactionManager.java

@@ -29,21 +29,23 @@ import org.springframework.transaction.support.DefaultTransactionStatus;
 
 /**
  * TransactionManager for managing LDAP transactions. Since transactions are not
- * supported in the LDAP protocol this class and its collaborators aims to
- * provide compensating transactions instead, i.e. should a transaction need to
- * be rolled back this TransactionManager will try to restore the original
- * original state using information recorded prior to each operation.
+ * supported in the LDAP protocol, this class and its collaborators aim to
+ * provide <em>compensating</em> transactions instead. Should a transaction
+ * need to be rolled back, this TransactionManager will try to restore the
+ * original state using information recorded prior to each operation. The
+ * operation where the original state is restored is called a compensating
+ * operation.
  * <p>
  * <b>NOTE:</b> The transactions provided by this TransactionManager are all
  * <i>client side</i> and are by no means 'real' transactions, in the sense
  * that we know them in the ordinary database world, e.g.:
  * <ul>
- * <li>Should the transaction failure be caused by a network failure there is
+ * <li>Should the transaction failure be caused by a network failure, there is
  * no way whatsoever that this TransactionManager can restore the database
- * state. In this case all possibilities for rollback will be utterly lost.</li>
+ * state. In this case, all possibilities for rollback will be utterly lost.</li>
  * <li>Transaction isolation is not provided, i.e. entries participating in a
  * transaction for one client may very well participate in another transaction
- * for another client at the same time. Should one of these transaction be
+ * for another client at the same time. Should one of these transactions be
  * rolled back, the outcome of this is undetermined, and may in the worst case
  * result in total failure.</li>
  * </ul>
@@ -51,8 +53,10 @@ import org.springframework.transaction.support.DefaultTransactionStatus;
  * <p>
  * While the points above should be noted and considered, the compensating
  * transaction approach will be perfectly sufficient for all but the most
- * unfortunate of circumstances, particularly considering the total absence of
- * transaction support which is normally the case working against LDAP servers.
+ * unfortunate of circumstances. Considering that there currently is a total
+ * absence of server-side transaction support in the LDAP world, being able to
+ * mark operations as transactional in the same way as for relational database
+ * operations is surely a step forward.
  * </p>
  * <p>
  * An LDAP transaction is tied to a {@link ContextSource}, to be supplied to
@@ -63,7 +67,7 @@ import org.springframework.transaction.support.DefaultTransactionStatus;
  * </p>
  * <p>
  * Using this TransactionManager along with
- * {@link TransactionAwareContextSourceProxy} all modifying operations (bind,
+ * {@link TransactionAwareContextSourceProxy}, all modifying operations (bind,
  * unbind, rebind, rename, modifyAttributes) in a transaction will be
  * intercepted. Each modification has its corresponding
  * {@link CompensatingTransactionOperationRecorder}, which collects the
@@ -74,18 +78,18 @@ import org.springframework.transaction.support.DefaultTransactionStatus;
  * </p>
  * <p>
  * For several of the operations, performing a rollback is pretty
- * straightforward. E.g. in order to roll back a rename operation it will only
- * be required to rename the entry back to its original position. For other
- * operations however, it's a bit more complicated. E.g. an unbind operation is
- * not possible to roll back by simply binding the entry back with the
- * attributes retrieved from the original entry. This is because it might not be
- * possible to get all the information from the original entry. Consequently,
- * the {@link UnbindOperationExecutor} will move the original entry to a
- * temporary location in its performOperation() method. In the commit() method
- * we already know that everything went well, so we're free to unbind the entry,
- * but the rollback operation will be to rename the entry back to its original
- * location. The same behaviour is used for rebind() operations. The operation
- * of calculating a temporary location for an entry is delegated to a
+ * straightforward. For example, in order to roll back a rename operation, it
+ * will only be required to rename the entry back to its original position. For
+ * other operations, however, it's a bit more complicated. An unbind operation
+ * is not possible to roll back by simply binding the entry back with the
+ * attributes retrieved from the original entry. It might not be possible to get
+ * all the information from the original entry. Consequently, the
+ * {@link UnbindOperationExecutor} will move the original entry to a temporary
+ * location in its performOperation() method. The commit() method will know that
+ * everything went well, so it will be OK to unbind the entry. The rollback
+ * operation will be to rename the entry back to its original location. The same
+ * behaviour is used for rebind() operations. The operation of calculating a
+ * temporary location for an entry is delegated to a
  * {@link TempEntryRenamingStrategy} (default
  * {@link DefaultTempEntryRenamingStrategy}), specified in
  * {@link #setRenamingStrategy(TempEntryRenamingStrategy)}.
@@ -104,6 +108,7 @@ import org.springframework.transaction.support.DefaultTransactionStatus;
  * @see DefaultCompensatingTransactionOperationManager
  * @see TempEntryRenamingStrategy
  * @see TransactionAwareContextSourceProxy
+ * @since 1.2
  */
 public class ContextSourceTransactionManager extends
         AbstractPlatformTransactionManager {
@@ -113,8 +118,6 @@ public class ContextSourceTransactionManager extends
     private ContextSourceTransactionManagerDelegate delegate = new ContextSourceTransactionManagerDelegate();
 
     /*
-     * (non-Javadoc)
-     * 
      * @see org.springframework.transaction.support.AbstractPlatformTransactionManager#doBegin(java.lang.Object,
      *      org.springframework.transaction.TransactionDefinition)
      */
@@ -124,8 +127,6 @@ public class ContextSourceTransactionManager extends
     }
 
     /*
-     * (non-Javadoc)
-     * 
      * @see org.springframework.transaction.support.AbstractPlatformTransactionManager#doCleanupAfterCompletion(java.lang.Object)
      */
     protected void doCleanupAfterCompletion(Object transaction) {
@@ -133,8 +134,6 @@ public class ContextSourceTransactionManager extends
     }
 
     /*
-     * (non-Javadoc)
-     * 
      * @see org.springframework.transaction.support.AbstractPlatformTransactionManager#doCommit(org.springframework.transaction.support.DefaultTransactionStatus)
      */
     protected void doCommit(DefaultTransactionStatus status)
@@ -143,8 +142,6 @@ public class ContextSourceTransactionManager extends
     }
 
     /*
-     * (non-Javadoc)
-     * 
      * @see org.springframework.transaction.support.AbstractPlatformTransactionManager#doGetTransaction()
      */
     protected Object doGetTransaction() throws TransactionException {
@@ -152,8 +149,6 @@ public class ContextSourceTransactionManager extends
     }
 
     /*
-     * (non-Javadoc)
-     * 
      * @see org.springframework.transaction.support.AbstractPlatformTransactionManager#doRollback(org.springframework.transaction.support.DefaultTransactionStatus)
      */
     protected void doRollback(DefaultTransactionStatus status)

spring-ldap/src/main/java/org/springframework/ldap/transaction/compensating/manager/ContextSourceTransactionManagerDelegate.java

@@ -37,6 +37,7 @@ import org.springframework.transaction.compensating.support.DefaultCompensatingT
  * @author Mattias Arthursson
  * @see ContextSourceTransactionManager
  * @see ContextSourceAndDataSourceTransactionManager
+ * @since 1.2
  */
 public class ContextSourceTransactionManagerDelegate extends
         AbstractCompensatingTransactionManagerDelegate {
@@ -71,10 +72,16 @@ public class ContextSourceTransactionManagerDelegate extends
         return contextSource;
     }
 
+    /*
+     * @see org.springframework.transaction.compensating.support.AbstractCompensatingTransactionManagerDelegate#getTransactionSynchronizationKey()
+     */
     protected Object getTransactionSynchronizationKey() {
         return getContextSource();
     }
 
+    /*
+     * @see org.springframework.transaction.compensating.support.AbstractCompensatingTransactionManagerDelegate#getNewHolder()
+     */
     protected CompensatingTransactionHolderSupport getNewHolder() {
         DirContext newCtx = getContextSource().getReadOnlyContext();
         DirContextHolder contextHolder = new DirContextHolder(
@@ -84,6 +91,9 @@ public class ContextSourceTransactionManagerDelegate extends
         return contextHolder;
     }
 
+    /*
+     * @see org.springframework.transaction.compensating.support.AbstractCompensatingTransactionManagerDelegate#closeTargetResource(org.springframework.transaction.compensating.support.CompensatingTransactionHolderSupport)
+     */
     protected void closeTargetResource(
             CompensatingTransactionHolderSupport transactionHolderSupport) {
         DirContextHolder contextHolder = (DirContextHolder) transactionHolderSupport;
@@ -108,5 +118,4 @@ public class ContextSourceTransactionManagerDelegate extends
     public void setRenamingStrategy(TempEntryRenamingStrategy renamingStrategy) {
         this.renamingStrategy = renamingStrategy;
     }
-
 }

spring-ldap/src/main/java/org/springframework/ldap/transaction/compensating/manager/DirContextHolder.java

@@ -28,7 +28,7 @@ import org.springframework.transaction.compensating.support.CompensatingTransact
  * for commit or rollback.
  * 
  * @author Mattias Arthursson
- * 
+ * @since 1.2
  */
 public class DirContextHolder extends CompensatingTransactionHolderSupport {
     private DirContext ctx;
@@ -65,8 +65,6 @@ public class DirContextHolder extends CompensatingTransactionHolderSupport {
     }
 
     /*
-     * (non-Javadoc)
-     * 
      * @see org.springframework.transaction.compensating.support.CompensatingTransactionHolderSupport#getTransactedResource()
      */
     protected Object getTransactedResource() {

spring-ldap/src/main/java/org/springframework/ldap/transaction/compensating/manager/TransactionAwareContextSourceProxy.java

@@ -27,13 +27,14 @@ import org.springframework.transaction.support.TransactionSynchronizationManager
 
 /**
  * A proxy for ContextSource to make sure that the returned DirContext objects
- * are aware of the surrounding transactions, making sure that the DirContext is
- * not closed during the transaction and that all modifying operations are
- * recorded, keeping track of the corresponding rollback operations. All
- * returned DirContext instances will be of the type
+ * are aware of the surrounding transactions. This makes sure that the
+ * DirContext is not closed during the transaction and that all modifying
+ * operations are recorded, keeping track of the corresponding rollback
+ * operations. All returned DirContext instances will be of the type
  * {@link TransactionAwareDirContextInvocationHandler}.
  * 
  * @author Mattias Arthursson
+ * @since 1.2
  */
 public class TransactionAwareContextSourceProxy implements ContextSource {
     private ContextSource target;
@@ -58,8 +59,6 @@ public class TransactionAwareContextSourceProxy implements ContextSource {
     }
 
     /*
-     * (non-Javadoc)
-     * 
      * @see org.springframework.ldap.core.ContextSource#getReadOnlyContext()
      */
     public DirContext getReadOnlyContext() throws NamingException {
@@ -70,7 +69,9 @@ public class TransactionAwareContextSourceProxy implements ContextSource {
             ContextSource target) {
         return (DirContext) Proxy
                 .newProxyInstance(DirContextProxy.class.getClassLoader(),
-                        new Class[] { LdapTransactionUtils.getActualTargetClass(context),
+                        new Class[] {
+                                LdapTransactionUtils
+                                        .getActualTargetClass(context),
                                 DirContextProxy.class },
                         new TransactionAwareDirContextInvocationHandler(
                                 context, target));
@@ -78,8 +79,6 @@ public class TransactionAwareContextSourceProxy implements ContextSource {
     }
 
     /*
-     * (non-Javadoc)
-     * 
      * @see org.springframework.ldap.core.ContextSource#getReadWriteContext()
      */
     public DirContext getReadWriteContext() throws NamingException {

spring-ldap/src/main/java/org/springframework/ldap/transaction/compensating/manager/TransactionAwareDirContextInvocationHandler.java

@@ -35,6 +35,7 @@ import org.springframework.transaction.support.TransactionSynchronizationManager
  * storing compensating rollback operations for them.
  * 
  * @author Mattias Arthursson
+ * @since 1.2
  */
 public class TransactionAwareDirContextInvocationHandler implements
         InvocationHandler {
@@ -62,8 +63,6 @@ public class TransactionAwareDirContextInvocationHandler implements
     }
 
     /*
-     * (non-Javadoc)
-     * 
      * @see java.lang.reflect.InvocationHandler#invoke(java.lang.Object,
      *      java.lang.reflect.Method, java.lang.Object[])
      */
@@ -121,5 +120,4 @@ public class TransactionAwareDirContextInvocationHandler implements
             log.debug("Leaving transactional context open");
         }
     }
-
 }