Added classes Connect.Call and StoredProcedureOutcome

.gitignore

@@ -2,3 +2,7 @@ target/
 .idea/
 *.iml
 .DS_Store
+bin/
+.classpath
+.project
+.settings/

pom.xml

@@ -79,6 +79,11 @@
             <artifactId>validation-api</artifactId>
             <scope>test</scope>
         </dependency>
+        <dependency>
+            <groupId>org.apache.commons</groupId>
+            <artifactId>commons-lang3</artifactId>
+            <scope>test</scope>
+        </dependency>
         <dependency>
             <groupId>org.aspectj</groupId>
             <artifactId>aspectjrt</artifactId>
@@ -428,6 +433,7 @@
                                 </goals>
                                 <configuration>
                                     <repoToken>${coveralls.token.jdbc}</repoToken>
+                                    <timestampFormat>yyyy-MM-dd'T'HH:mm:ss</timestampFormat>
                                 </configuration>
                             </execution>
                         </executions>

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

@@ -53,22 +53,52 @@ interface Connect {
      */
     PreparedStatement open(Connection conn) throws SQLException;
 
+    /**
+     * Connect which opens a <b>CallableStatement</b>, which
+     * is used for calling stored procedures.
+     */
+    final class Call implements Connect {
+
+        /**
+         * SQL function call.
+         */
+        private final String sql;
+
+        /**
+         * Ctor.
+         * @param query Query
+         */
+        public Call(final String query) {
+            this.sql = query;
+        }
+
+        @Override
+        public PreparedStatement open(final Connection conn)
+            throws SQLException {
+            return conn.prepareCall(this.sql);
+        }
+
+    }
+
     /**
      * Plain, without keys.
      */
     @Immutable
     final class Plain implements Connect {
+
         /**
          * SQL query.
          */
         private final transient String sql;
+
         /**
          * Ctor.
          * @param query Query
          */
         public Plain(final String query) {
             this.sql = query;
         }
+
         @Override
         public PreparedStatement open(final Connection conn)
             throws SQLException {
@@ -81,17 +111,20 @@ public PreparedStatement open(final Connection conn)
      */
     @Immutable
     final class WithKeys implements Connect {
+
         /**
          * SQL query.
          */
         private final transient String sql;
+
         /**
          * Ctor.
          * @param query Query
          */
         public WithKeys(final String query) {
             this.sql = query;
         }
+
         @Override
         public PreparedStatement open(final Connection conn)
             throws SQLException {
@@ -100,6 +133,7 @@ public PreparedStatement open(final Connection conn)
                 Statement.RETURN_GENERATED_KEYS
             );
         }
+
     }
 
 }

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

@@ -106,6 +106,10 @@
  * @author Yegor Bugayenko ([email protected])
  * @version $Id$
  * @since 0.1.8
+ * @checkstyle ClassDataAbstractionCouplingCheck (500 lines)
+ * @todo #51:30min Refactor this class to avoid too much coupling.
+ *  For instance, CRUD operations could be performed by another class.
+ *  Don't forget to remove the suppressions that become obsolete afterwards.
  */
 @ToString
 @EqualsAndHashCode(of = { "source", "connection", "args", "auto", "query" })
@@ -308,6 +312,26 @@ public <T> T update(final Outcome<T> outcome)
         );
     }
 
+    /**
+     * Call an SQL stored procedure.
+     *
+     * <p>JDBC connection is opened and, optionally, commited 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.
+     *
+     * @param <T> Type of result expected
+     * @param outcome Outcome of the operation
+     * @return Result of type T
+     * @throws SQLException If fails
+     */
+    public <T> T call(final Outcome<T> outcome)
+        throws SQLException {
+        return this.run(
+            outcome, new Connect.Call(this.query), Request.EXECUTE_UPDATE
+        );
+    }
+
     /**
      * Make SQL request expecting no response from the server.
      *

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

@@ -0,0 +1,92 @@
+/**
+ * Copyright (c) 2012-2015, jcabi.com
+ * All rights reserved.
+ *
+ * Redistribution and use in source and binary forms, with or without
+ * modification, are permitted provided that the following conditions
+ * are met: 1) Redistributions of source code must retain the above
+ * copyright notice, this list of conditions and the following
+ * disclaimer. 2) Redistributions in binary form must reproduce the above
+ * copyright notice, this list of conditions and the following
+ * disclaimer in the documentation and/or other materials provided
+ * with the distribution. 3) Neither the name of the jcabi.com nor
+ * the names of its contributors may be used to endorse or promote
+ * products derived from this software without specific prior written
+ * permission.
+ *
+ * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+ * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT
+ * NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND
+ * FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL
+ * THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT,
+ * INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
+ * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+ * SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
+ * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
+ * STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+ * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
+ * OF THE POSSIBILITY OF SUCH DAMAGE.
+ */
+package com.jcabi.jdbc;
+
+import com.jcabi.aspects.Immutable;
+import java.sql.CallableStatement;
+import java.sql.ResultSet;
+import java.sql.SQLException;
+import java.sql.Statement;
+import lombok.EqualsAndHashCode;
+import lombok.ToString;
+
+/**
+ * Outcome of a stored procedure with OUT parameters.
+ * @author Mihai Andronache ([email protected])
+ * @version $Id$
+ * @since 0.17
+ * @param <T> Type of the returned result, which <b>has to be</b> Object[]
+ */
+@Immutable
+@ToString
+@EqualsAndHashCode
+public final class StoredProcedureOutcome<T> implements Outcome<T> {
+
+    /**
+     * OUT parameters' indexes.
+     */
+    @Immutable.Array
+    private final transient int[] indexes;
+
+    /**
+     * Ctor.
+     * @param indexes Indexes of the OUT params.
+     *  <b>Index count starts from 1</b>.
+     */
+    public StoredProcedureOutcome(final int... indexes) {
+        if (indexes.length == 0) {
+            throw new IllegalArgumentException(
+                "At least 1 OUT param's index needs to be specified!"
+            );
+        }
+        final int size = indexes.length;
+        this.indexes = new int[size];
+        for (int idx = 0; idx < size; ++idx) {
+            this.indexes[idx] = indexes[idx];
+        }
+    }
+
+    @Override
+    @SuppressWarnings("unchecked")
+    public T handle(final ResultSet rset, final Statement stmt)
+        throws SQLException {
+        final int params = this.indexes.length;
+        final Object[] outs = new Object[params];
+        if (stmt instanceof CallableStatement) {
+            for (int idx = 0; idx < params; ++idx) {
+                outs[idx] = ((CallableStatement) stmt).getObject(
+                    this.indexes[idx]
+                );
+            }
+        }
+        return (T) outs;
+    }
+
+}

src/test/java/com/jcabi/jdbc/JdbcSessionITCase.java

@@ -31,7 +31,15 @@
 
 import com.jcabi.aspects.Tv;
 import com.jolbox.bonecp.BoneCPDataSource;
+import java.sql.CallableStatement;
+import java.sql.PreparedStatement;
+import java.sql.SQLException;
+import java.sql.Types;
+import java.util.Date;
 import javax.sql.DataSource;
+import org.apache.commons.lang3.StringUtils;
+import org.hamcrest.MatcherAssert;
+import org.hamcrest.Matchers;
 import org.junit.Assume;
 import org.junit.Before;
 import org.junit.Test;
@@ -90,6 +98,93 @@ public void changesTransactionIsolationLevel() throws Exception {
         new JdbcSession(source).sql("VACUUM").execute();
     }
 
+    /**
+     * JdbcSession can run a function (stored procedure) with
+     * output parameters.
+     * @throws Exception If something goes wrong
+     */
+    @Test
+    public void callsFunctionWithOutParam() throws Exception {
+        final DataSource source = JdbcSessionITCase.source();
+        new JdbcSession(source).autocommit(false).sql(
+            "CREATE TABLE IF NOT EXISTS users (name VARCHAR(50))"
+        ).execute().sql("INSERT INTO users (name) VALUES (?)")
+        .set("Jeff Charles").execute().sql(
+            StringUtils.join(
+                "CREATE OR REPLACE FUNCTION fetchUser(username OUT text,",
+                " day OUT date)",
+                " AS $$ BEGIN SELECT name, CURRENT_DATE INTO username, day",
+                " FROM users; END; $$ LANGUAGE plpgsql;"
+            )
+        ).execute().commit();
+        final Object[] result = new JdbcSession(source)
+            .sql("{call fetchUser(?, ?)}")
+            .prepare(
+                new Preparation() {
+                    @Override
+                    public void
+                        prepare(final PreparedStatement stmt)
+                        throws SQLException {
+                            final CallableStatement cstmt =
+                                (CallableStatement) stmt;
+                            cstmt.registerOutParameter(1, Types.VARCHAR);
+                            cstmt.registerOutParameter(2, Types.DATE);
+                    }
+                }
+             )
+            .call(new StoredProcedureOutcome<Object[]>(1, 2));
+        MatcherAssert.assertThat(result.length, Matchers.is(2));
+        MatcherAssert.assertThat(
+            result[0].toString(),
+            Matchers.containsString("Charles")
+        );
+        MatcherAssert.assertThat(
+            (Date) result[1],
+            Matchers.notNullValue()
+        );
+    }
+
+    /**
+     * JdbcSession can run a function (stored procedure) with
+     * input and output parameters.
+     * @throws Exception If something goes wrong
+     */
+    @Test
+    public void callsFunctionWithInOutParam() throws Exception {
+        final DataSource source = JdbcSessionITCase.source();
+        new JdbcSession(source).autocommit(false).sql(
+            "CREATE TABLE IF NOT EXISTS usersids (id INTEGER, name VARCHAR(50))"
+        ).execute().sql("INSERT INTO usersids (id, name) VALUES (?, ?)")
+        .set(1).set("Marco Polo").execute().sql(
+            StringUtils.join(
+                "CREATE OR REPLACE FUNCTION fetchUserById(uid IN INTEGER,",
+                " usrnm OUT text) AS $$ BEGIN",
+                " SELECT name INTO usrnm FROM usersids WHERE id=uid;",
+                " END; $$ LANGUAGE plpgsql;"
+            )
+        ).execute().commit();
+        final Object[] result = new JdbcSession(source)
+            .sql("{call fetchUserById(?, ?)}")
+            .set(1)
+            .prepare(
+                new Preparation() {
+                    @Override
+                    public void
+                        prepare(final PreparedStatement stmt)
+                        throws SQLException {
+                            ((CallableStatement) stmt)
+                                .registerOutParameter(2, Types.VARCHAR);
+                    }
+                }
+             )
+            .call(new StoredProcedureOutcome<Object[]>(2));
+        MatcherAssert.assertThat(result.length, Matchers.is(1));
+        MatcherAssert.assertThat(
+            result[0].toString(),
+            Matchers.containsString("Polo")
+        );
+    }
+
     /**
      * Get data source.
      * @return Source