/*
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 * http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
package org.jdbi.v3.tweak;

import org.jdbi.v3.Handle;
import org.jdbi.v3.TransactionCallback;
import org.jdbi.v3.TransactionIsolationLevel;

/**
 * Interface which defines callbacks to be used when transaction methods are called on a handle.
 * Used by specifying on an <code>IDBI</code> instance. All <code>Handle</code> instances
 * opened from that <code>IDBI</code> will use the handler specified.
 * <p />
 * The default implementation, <code>ConnectionTransactionHandler</code>, explicitely manages
 * the transactions on the underlying JDBC <code>Connection</code>.
 */
public interface TransactionHandler
{
    /**
     * Called when a transaction is started
     */
    void begin(Handle handle); // TODO consider having this return a TransactionStatus

    /**
     * Called when a transaction is committed
     */
    void commit(Handle handle);

    /**
     * Called when a transaction is rolled back
     */
    void rollback(Handle handle);

    /**
     * Roll back to a named checkpoint
     * @param handle the handle the rollback is being performed on
     * @param name the name of the checkpoint to rollback to
     */
    void rollback(Handle handle, String name);

    /**
     * Called to test if a handle is in a transaction
     */
    boolean isInTransaction(Handle handle);

    /**
     * Create a new checkpoint (savepoint in JDBC terminology)
     *
     * @param handle the handle on which the transaction is being checkpointed
     * @param name The name of the chckpoint, used to rollback to or release late
     */
    void checkpoint(Handle handle, String name);

    /**
     * Release a previously created checkpoint
     *
     * @param handle the handle on which the checkpoint is being released
     * @param checkpointName the checkpoint to release
     */
    void release(Handle handle, String checkpointName);

    /**
     * Run a transaction.
     * @see Handle#inTransaction(TransactionCallback)
     */
    <R, X extends Exception> R inTransaction(Handle handle,
                                             TransactionCallback<R, X> callback) throws X;

    /**
     * Run a transaction.
     * @see Handle#inTransaction(TransactionIsolationLevel, TransactionCallback)
     */
    <R, X extends Exception> R inTransaction(Handle handle,
                                             TransactionIsolationLevel level,
                                             TransactionCallback<R, X> callback) throws X;

}

@@ -824,17 +824,15 @@
 on a
-n
  %3Ccode%3E
-I
 DBI%3C
@@ -908,17 +908,16 @@
 t %3Ccode%3E
-I
 DBI%3C/cod
@@ -955,15 +955,16 @@
 ed.%0A
+ *%0A
  * %3Cp
- /
 %3E%0A *
@@ -1043,17 +1043,16 @@
 explicit
-e
 ly manag
@@ -1122,16 +1122,24 @@
 /code%3E.%0A
+ * %3C/p%3E%0A
  */%0Apubl
@@ -1220,24 +1220,99 @@
  is started%0A
+     *%0A     * @param handle the handle the transaction is being started on%0A
      */%0A    
@@ -1445,24 +1445,96 @@
 s committed%0A
+     *%0A     * @param handle the handle the commit is being performed on%0A
      */%0A    
@@ -1618,16 +1618,90 @@
 ed back%0A
+     *%0A     * @param handle the handle the rollback is being performed on%0A
      */%0A
@@ -1778,24 +1778,31 @@
  checkpoint%0A
+     *%0A
      * @para
@@ -1992,27 +1992,73 @@
   * 
-Called to test if a
+@param handle the handle to test%0A     * @return whether the given
  han
@@ -2731,248 +2731,1056 @@
    *
- @see Handle#inTransaction(TransactionCallback)%0A     */%0A    %3CR, X extends Exception%3E R inTransaction(Handle handle,%0A                                             TransactionCallback%3CR, X%3E callback) throws X;%0A%0A    /**%0A     * Run a transaction
+%0A     * @param handle the handle to the database%0A     * @param callback a callback which will receive the open handle, in a transaction.%0A     * @param %3CR%3E the callback return type%0A     * @param %3CX%3E the exception type thrown by the callback, if any%0A     *%0A     * @return the value returned by the callback.%0A     *%0A     * @throws X any exception thrown by the callback.%0A     * @see Handle#inTransaction(TransactionCallback)%0A     */%0A    %3CR, X extends Exception%3E R inTransaction(Handle handle,%0A                                             TransactionCallback%3CR, X%3E callback) throws X;%0A%0A    /**%0A     * Run a transaction.%0A     *%0A     * @param handle the handle to the database%0A     * @param level the isolation level for the transaction%0A     * @param callback a callback which will receive the open handle, in a transaction.%0A     * @param %3CR%3E the callback return type%0A     * @param %3CX%3E the exception type thrown by the callback, if any%0A     *%0A     * @return the value returned by the callback.%0A     *%0A     * @throws X any exception thrown by the callback
 .%0A  

Fix up TransactionHandler javadoc