Merge branch '__rultor'

LICENSE.txt

@@ -1,4 +1,4 @@
-Copyright (c) 2012-2022, jcabi.com
+Copyright (c) 2012-2023, jcabi.com
 All rights reserved.
 
 Redistribution and use in source and binary forms, with or without

pom.xml

@@ -1,6 +1,6 @@
 <?xml version="1.0"?>
 <!--
-Copyright (c) 2012-2022, jcabi.com
+Copyright (c) 2012-2023, jcabi.com
 All rights reserved.
 
 Redistribution and use in source and binary forms, with or without
@@ -60,17 +60,23 @@ OF THE POSSIBILITY OF SUCH DAMAGE.
     </site>
   </distributionManagement>
   <dependencies>
-    <dependency>
-      <groupId>com.jcabi</groupId>
-      <artifactId>jcabi-aspects</artifactId>
-      <version>0.24.1</version>
-      <scope>test</scope>
-    </dependency>
     <dependency>
       <groupId>org.projectlombok</groupId>
       <artifactId>lombok</artifactId>
       <version>1.18.28</version>
     </dependency>
+    <dependency>
+      <groupId>org.aspectj</groupId>
+      <artifactId>aspectjrt</artifactId>
+      <version>1.9.19</version>
+      <scope>runtime</scope>
+    </dependency>
+    <dependency>
+      <groupId>com.jcabi</groupId>
+      <artifactId>jcabi-aspects</artifactId>
+      <version>0.25.1</version>
+      <scope>test</scope>
+    </dependency>
     <dependency>
       <groupId>javax.validation</groupId>
       <artifactId>validation-api</artifactId>
@@ -83,12 +89,6 @@ OF THE POSSIBILITY OF SUCH DAMAGE.
       <version>3.12.0</version>
       <scope>test</scope>
     </dependency>
-    <dependency>
-      <groupId>org.aspectj</groupId>
-      <artifactId>aspectjrt</artifactId>
-      <version>1.9.19</version>
-      <scope>runtime</scope>
-    </dependency>
     <dependency>
       <groupId>com.h2database</groupId>
       <artifactId>h2</artifactId>
@@ -105,7 +105,7 @@ OF THE POSSIBILITY OF SUCH DAMAGE.
       <groupId>mysql</groupId>
       <artifactId>mysql-connector-java</artifactId>
       <version>8.0.33</version>
-      <scope>provided</scope>
+      <scope>test</scope>
     </dependency>
     <dependency>
       <groupId>com.jolbox</groupId>

src/main/java/com/jcabi/jdbc/ColumnOutcome.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2012-2022, jcabi.com
+ * Copyright (c) 2012-2023, jcabi.com
  * All rights reserved.
  *
  * Redistribution and use in source and binary forms, with or without

src/main/java/com/jcabi/jdbc/Connect.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2012-2022, jcabi.com
+ * Copyright (c) 2012-2023, jcabi.com
  * All rights reserved.
  *
  * Redistribution and use in source and binary forms, with or without

src/main/java/com/jcabi/jdbc/DefaultMappings.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2012-2022, jcabi.com
+ * Copyright (c) 2012-2023, jcabi.com
  * All rights reserved.
  *
  * Redistribution and use in source and binary forms, with or without
@@ -121,7 +121,7 @@ private DefaultMappings(
     public <X> Outcome.Mapping<X> forType(final Class<? extends X> tpe) {
         if (!this.map.containsKey(tpe)) {
             throw new IllegalArgumentException(
-                String.format("type %s is not supported", tpe.getName())
+                String.format("Type %s is not supported", tpe.getName())
             );
         }
         return (Outcome.Mapping<X>) this.map.get(tpe);

src/main/java/com/jcabi/jdbc/JdbcSession.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2012-2022, jcabi.com
+ * Copyright (c) 2012-2023, jcabi.com
  * All rights reserved.
  *
  * Redistribution and use in source and binary forms, with or without
@@ -101,38 +101,39 @@
  *   .sql("SHUTDOWN COMPACT")
  *   .execute();</pre>
  *
- * <b>IMPORTANT:</b>
+ * <p><b>IMPORTANT:</b></p>
+ *
  * <p>If you rely on one specific {@link Connection} instance, be careful if
  * you are using it in more places, especially if more references of this class
  * use it - one of those references might close the connection if you forget
- * to call {@link #autocommit(false)}
- * </p>
- * <b>E.g.</b>
- * <pre>
- * Connection connection = [...];
- * DataSource ds = new StaticSource(connection);
- * new JdbcSession(ds)
- *  .sql("SQL STATEMENT")
- *  .execute();
- * new JdbcSession(ds)
- *  .sql("SQL STATEMENT 2")
- *  .execute();</pre>
+ * to call {@link JdbcSession#autocommit(boolean)} with {@code false} as an argument,
+ * for example:</p>
+ *
+ * <pre> Connection connection = [...];
+ *   DataSource ds = new StaticSource(connection);
+ *   new JdbcSession(ds)
+ *     .sql("SQL STATEMENT")
+ *     .execute();
+ *   new JdbcSession(ds)
+ *     .sql("SQL STATEMENT 2")
+ *     .execute();</pre>
+
  * <p>The above example will <b>fail</b> because the first JdbcSession closes
  * the connection, and the next one tries to work with it closed. In order to
  * not have this failure, the first session has to call
- * {@link #autocommit(false)}, like this:
- * </p>
- * <pre>
- * Connection connection = [...];
- * DataSource ds = new StaticSource(connection);
- * new JdbcSession(ds)
- *  <b>.autocommit(false)</b>
- *  .sql("SQL STATEMENT")
- *  .execute();
- * new JdbcSession(ds)
- *  .sql("SQL STATEMENT 2")
- *  .execute();</pre>
- * <p>This class is thread-safe.
+ * {@link #autocommit(boolean)} with {@code false} as an argument, like this:</p>
+ *
+ * <pre> Connection connection = [...];
+ *   DataSource ds = new StaticSource(connection);
+ *   new JdbcSession(ds)
+ *     .autocommit(false)
+ *     .sql("SQL STATEMENT")
+ *     .execute();
+ *   new JdbcSession(ds)
+ *     .sql("SQL STATEMENT 2")
+ *     .execute();</pre>
+ *
+ * <p>This class is thread-safe.</p>
  *
  * @since 0.1.8
  * @todo #51:30min Refactor this class to avoid too much coupling.
@@ -176,11 +177,13 @@ public final class JdbcSession {
     private transient String query;
 
     /**
-     * Public ctor.<br><br>
-     * If all you have is a {@link Connection}, wrap it inside our
+     * Public ctor.
+     *
+     * <p>If all you have is a {@link Connection}, wrap it inside our
      * {@link StaticSource}, but make sure you understand the autocommit
      * mechanism we have in place here. Read the class' javadoc (especially the
-     * last paragraph, marked with <b>IMPORTANT</b>).
+     * last paragraph, marked with <b>IMPORTANT</b>).</p>
+     *
      * @param src Data source
      */
     @SuppressWarnings("PMD.ConstructorOnlyInitializesOrCallOtherConstructors")
@@ -254,6 +257,7 @@ public JdbcSession set(final Object value) {
 
     /**
      * Run this preparation before executing the statement.
+     *
      * @param prp Preparation
      * @return This object
      * @since 0.13
@@ -267,6 +271,7 @@ public JdbcSession prepare(final Preparation prp) {
 
     /**
      * Clear all pre-set parameters (args, preparations, etc).
+     *
      * @return This object
      * @since 0.13
      */
@@ -282,13 +287,14 @@ public JdbcSession clear() {
     /**
      * Commit the transaction (calls {@link Connection#commit()} and then
      * {@link Connection#close()}).
+     *
      * @throws SQLException If fails to do the SQL operation
      */
     public void commit() throws SQLException {
         final Connection conn = this.connection.get();
         if (conn == null) {
             throw new IllegalStateException(
-                "connection is not open, can't commit"
+                "Connection is not open, can't commit"
             );
         }
         conn.commit();
@@ -298,13 +304,14 @@ public void commit() throws SQLException {
     /**
      * Rollback the transaction (calls {@link Connection#rollback()} and then
      * {@link Connection#close()}).
+     *
      * @throws SQLException If fails to do the SQL operation
      */
     public void rollback() throws SQLException {
         final Connection conn = this.connection.get();
         if (conn == null) {
             throw new IllegalStateException(
-                "connection is not open, can't rollback"
+                "Connection is not open, can't rollback"
             );
         }
         conn.rollback();
@@ -315,9 +322,9 @@ public void rollback() throws SQLException {
      * Make SQL {@code INSERT} request.
      *
      * <p>{@link Outcome} will receive
-     * a {@link ResultSet} of generated keys.
+     * a {@link ResultSet} of generated keys.</p>
      *
-     * <p>JDBC connection is opened and, optionally, closed by this method.
+     * <p>JDBC connection is opened and, optionally, closed by this method.</p>
      *
      * @param outcome The outcome of the operation
      * @param <T> Type of response
@@ -336,7 +343,7 @@ public <T> T insert(final Outcome<T> outcome)
     /**
      * Make SQL {@code UPDATE} request.
      *
-     * <p>JDBC connection is opened and, optionally, closed by this method.
+     * <p>JDBC connection is opened and, optionally, closed by this method.</p>
      *
      * @param outcome Outcome of the operation
      * @param <T> Type of result expected
@@ -355,10 +362,10 @@ public <T> T update(final Outcome<T> outcome)
     /**
      * Call an SQL stored procedure.
      *
-     * <p>JDBC connection is opened and, optionally, commited by this
+     * <p>JDBC connection is opened and, optionally, committed by this
      * method, depending on the <b>autocommit</b> class attribute:
-     * if it's value is true, the connection will be commited after
-     * this call.
+     * if it's value is true, the connection will be committed after
+     * this call.</p>
      *
      * @param outcome Outcome of the operation
      * @param <T> Type of result expected
@@ -380,9 +387,9 @@ public <T> T call(final Outcome<T> outcome)
      * instructions that return no data back. Main difference between this
      * one and {@code #execute()} is that the later requests JDBC to return
      * generated keys. When SQL server doesn't return any keys this may
-     * cause runtime exceptions in JDBC.
+     * cause runtime exceptions in JDBC.</p>
      *
-     * <p>JDBC connection is opened and, optionally, closed by this method.
+     * <p>JDBC connection is opened and, optionally, closed by this method.</p>
      *
      * @return This object
      * @throws SQLException If fails
@@ -410,9 +417,9 @@ public JdbcSession execute() throws SQLException {
     /**
      * Make SQL {@code SELECT} request.
      *
-     * <p>JDBC connection is opened and, optionally, closed by this method.
+     * <p>JDBC connection is opened and, optionally, closed by this method.</p>
      *
-     * @param outcome The outcome of the operaton
+     * @param outcome The outcome of the operation
      * @param <T> Type of response
      * @return The result
      * @throws SQLException If fails
@@ -428,6 +435,7 @@ public <T> T select(final Outcome<T> outcome)
 
     /**
      * Run with this outcome, and this fetcher.
+     *
      * @param outcome The outcome of the operation
      * @param connect Connect
      * @param request Request
@@ -436,16 +444,17 @@ public <T> T select(final Outcome<T> outcome)
      * @throws SQLException If fails
      * @checkstyle ExecutableStatementCount (100 lines)
      */
+    @SuppressWarnings({"PMD.PreserveStackTrace", "PMD.ExceptionAsFlowControl"})
     private <T> T run(final Outcome<T> outcome,
         final Connect connect, final Request request)
         throws SQLException {
         if (this.query == null) {
-            throw new IllegalStateException("call #sql() first");
+            throw new IllegalStateException("Call #sql() first");
         }
         final Connection conn = this.connect();
+        conn.setAutoCommit(this.auto);
         final T result;
         try {
-            conn.setAutoCommit(this.auto);
             final PreparedStatement stmt = connect.open(conn);
             try {
                 this.configure(stmt);
@@ -463,8 +472,18 @@ private <T> T run(final Outcome<T> outcome,
             }
         } catch (final SQLException ex) {
             if (!this.auto) {
-                conn.rollback();
-                this.disconnect();
+                try {
+                    conn.rollback();
+                    this.disconnect();
+                } catch (final SQLException exc) {
+                    throw new SQLException(
+                        String.format(
+                            "Failed to rollback after failure: %s",
+                            exc.getMessage()
+                        ),
+                        ex
+                    );
+                }
             }
             throw new SQLException(ex);
         } finally {
@@ -478,6 +497,7 @@ private <T> T run(final Outcome<T> outcome,
 
     /**
      * Open connection and cache it locally in the class.
+     *
      * @return Connection to use
      * @throws SQLException If fails
      */
@@ -492,20 +512,22 @@ private Connection connect() throws SQLException {
 
     /**
      * Close connection if it's open (runtime exception otherwise).
+     *
      * @throws SQLException If fails to do the SQL operation
      */
     private void disconnect() throws SQLException {
         final Connection conn = this.connection.getAndSet(null);
         if (conn == null) {
             throw new IllegalStateException(
-                "connection is not open, can't close"
+                "Connection is not open, can't close"
             );
         }
         conn.close();
     }
 
     /**
      * Configure the statement.
+     *
      * @param stmt Statement
      * @throws SQLException If fails
      */

src/main/java/com/jcabi/jdbc/ListOutcome.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2012-2022, jcabi.com
+ * Copyright (c) 2012-2023, jcabi.com
  * All rights reserved.
  *
  * Redistribution and use in source and binary forms, with or without

src/main/java/com/jcabi/jdbc/Outcome.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2012-2022, jcabi.com
+ * Copyright (c) 2012-2023, jcabi.com
  * All rights reserved.
  *
  * Redistribution and use in source and binary forms, with or without

src/main/java/com/jcabi/jdbc/Preparation.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2012-2022, jcabi.com
+ * Copyright (c) 2012-2023, jcabi.com
  * All rights reserved.
  *
  * Redistribution and use in source and binary forms, with or without