ENH: Add Transaction.rollbackAndContinue()

Typically useful for handling DuplicateKeyException where we expect
DuplicateKeyException to be thrown and catch it with the intention of
continuing processing using the same transaction.

Note that some databases like Oracle do not require this explicit
rollback() and would work without the rollbackAndContinue(). Postgres
in particular requires the rollback() call on the underlying connection
such that we can continue using that transaction/java.sql.Connection.

Note that in the existing test we can see that rollbackAndContinue()
is pretty close to being syntactic sugar. I think adding rollbackAndContinue()
is justified and complements the existing commitAndContinue().

ebean-api/src/main/java/io/ebean/DuplicateKeyException.java

@@ -2,6 +2,28 @@ package io.ebean;
 
 /**
  * Thrown when a duplicate is attempted on a unique constraint.
+ * <p>
+ * In terms of catching this exception with the view of continuing processing
+ * using the same transaction look to use {@link Transaction#rollbackAndContinue()}.
+ *
+ * <pre>{@code
+ *
+ *   try (Transaction txn = database.beginTransaction()) {
+ *
+ *     try {
+ *       ...
+ *       database.save(bean);
+ *       database.flush();
+ *     } catch (DuplicateKeyException e) {
+ *       // carry on processing using the transaction
+ *       txn.rollbackAndContinue();
+ *       ...
+ *     }
+ *
+ *     txn.commit();
+ *   }
+ *
+ * }</pre>
  */
 public class DuplicateKeyException extends DataIntegrityException {
   private static final long serialVersionUID = -4771932723285724817L;

ebean-api/src/main/java/io/ebean/Transaction.java

@@ -144,6 +144,35 @@ public interface Transaction extends AutoCloseable {
    */
   void rollback(Throwable e) throws PersistenceException;
 
+  /**
+   * Performs a rollback on the underlying JDBC connection with the intention of
+   * continuing to use this same transaction and performing a commit or rollback
+   * later to complete the transaction.
+   * <p>
+   * Typically used when catching {@link DuplicateKeyException} where we wish to
+   * rollback work done at that point but carry on processing using the transaction.
+   *
+   * <pre>{@code
+   *
+   *   try (Transaction txn = database.beginTransaction()) {
+   *
+   *     try {
+   *       ...
+   *       database.save(bean);
+   *       database.flush();
+   *     } catch (DuplicateKeyException e) {
+   *       // carry on processing using the transaction
+   *       txn.rollbackAndContinue();
+   *       ...
+   *     }
+   *
+   *     txn.commit();
+   *   }
+   *
+   * }</pre>
+   */
+  void rollbackAndContinue();
+
   /**
    * Set when we want nested transactions to use Savepoint's.
    * <p>