Added classes Connect.Call and StoredProcedureOutcome

.gitignore

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

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,7 @@
  * @author Yegor Bugayenko ([email protected])
  * @version $Id$
  * @since 0.1.8
+ * @checkstyle ClassDataAbstractionCouplingCheck (500 lines)
  */
 @ToString
 @EqualsAndHashCode(of = { "source", "connection", "args", "auto", "query" })
@@ -308,6 +309,25 @@ public <T> T update(final Outcome<T> outcome)
         );
     }
 
+    /**
+     * Call an SQL stored procedure.
+     *
+     * <p>JDBC connection is opened and, optionally, closed by this method.
+     *
+     * @param <T> Type of result expected
+     * @param outcome Outcome of the operation
+     * @return This object
+     * @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,111 @@
+/**
+ * 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.7
+ * @param <T> Type of items
+ */
+@Immutable
+@ToString
+@EqualsAndHashCode(of = { "outpidx" })
+public final class StoredProcedureOutcome<T> implements Outcome<T> {
+
+    /**
+     * Indexes of the OUT params.
+     */
+    @Immutable.Array
+    private final transient int[] outpidx;
+
+    /**
+     * Ctor.
+     * @param nrop Number of OUT params. Has to be > 0.
+     *  If this ctor is used, it is assumed that the OUT parameters
+     *  are from index 1 to including nrop.
+     */
+    public StoredProcedureOutcome(final int nrop) {
+        if (nrop <= 0) {
+            throw new IllegalArgumentException(
+                "Nr of out params has to be a positive int!"
+            );
+        }
+        this.outpidx = new int[nrop];
+        for (int idx = 0; idx < nrop; ++idx) {
+            this.outpidx[idx] = idx + 1;
+        }
+    }
+
+    /**
+     * Ctor.
+     * @param opidx Indexes of the OUT params.
+     *  <b>Index count starts from 1</b>.
+     */
+    public StoredProcedureOutcome(final int... opidx) {
+        if (opidx == null || opidx.length == 0) {
+            throw new IllegalArgumentException(
+                "At least 1 OUT param's index needs to be specified!"
+            );
+        }
+        final int size = opidx.length;
+        this.outpidx = new int[size];
+        for (int idx = 0; idx < size; ++idx) {
+            this.outpidx[idx] = opidx[idx];
+        }
+    }
+
+    @Override
+    @SuppressWarnings("unchecked")
+    public T handle(
+        final ResultSet rset, final Statement stmt
+    ) throws SQLException {
+        final int nrop = this.outpidx.length;
+        final Object[] outs = new Object[nrop];
+        if (stmt instanceof CallableStatement) {
+            for (int idx = 0; idx < nrop; ++idx) {
+                outs[idx] = ((CallableStatement) stmt).getObject(
+                    this.outpidx[idx]
+                );
+            }
+        }
+        return (T) outs;
+    }
+
+}

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

@@ -31,7 +31,13 @@
 
 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 javax.sql.DataSource;
+import org.hamcrest.MatcherAssert;
+import org.hamcrest.Matchers;
 import org.junit.Assume;
 import org.junit.Before;
 import org.junit.Test;
@@ -40,6 +46,7 @@
  * Integration case for {@link JdbcSession}.
  * @author Yegor Bugayenko ([email protected])
  * @version $Id$
+ * @checkstyle StringLiteralsConcatenationCheck (300 lines)
  */
 public final class JdbcSessionITCase {
 
@@ -90,6 +97,82 @@ 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 dsrc = JdbcSessionITCase.source();
+        new JdbcSession(dsrc).autocommit(false).sql(
+            "CREATE TABLE IF NOT EXISTS users (name VARCHAR(50))"
+        ).execute().sql("INSERT INTO users (name) VALUES (?)")
+        .set("Jeff Charles").execute().sql(
+            "CREATE OR REPLACE FUNCTION getUser(username OUT text)"
+            + " AS $$ BEGIN SELECT name INTO username from  users; END;"
+            + " $$ LANGUAGE plpgsql;"
+        ).execute().commit();
+        final Object[] result = new JdbcSession(dsrc)
+            .sql("{call getUser(?)}")
+            .prepare(
+                new Preparation() {
+                    @Override
+                    public void prepare(
+                        final PreparedStatement stmt
+                    ) throws SQLException {
+                        ((CallableStatement) stmt)
+                            .registerOutParameter(1, Types.VARCHAR);
+                    }
+                }
+             )
+            .call(new StoredProcedureOutcome<Object[]>(1));
+        MatcherAssert.assertThat(result.length, Matchers.is(1));
+        MatcherAssert.assertThat(
+            result[0].toString(),
+            Matchers.containsString("Charles")
+        );
+    }
+
+    /**
+     * 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 dsrc = JdbcSessionITCase.source();
+        new JdbcSession(dsrc).autocommit(false).sql(
+            "CREATE TABLE IF NOT EXISTS usersid (id INTEGER, name VARCHAR(50))"
+        ).execute().sql("INSERT INTO usersid (id, name) VALUES (?, ?)")
+        .set(1).set("Marco Polo").execute().sql(
+            "CREATE OR REPLACE FUNCTION getUserById(uid IN INTEGER,"
+            + " usrnm OUT text) AS $$ BEGIN"
+            + " SELECT name INTO usrnm FROM  usersid WHERE id=uid;"
+            + " END; $$ LANGUAGE plpgsql;"
+        ).execute().commit();
+        final Object[] result = new JdbcSession(dsrc)
+            .sql("{call getUserById(?, ?)}")
+            .set(1)
+            .prepare(
+                new Preparation() {
+                    @Override
+                    public void prepare(
+                        final PreparedStatement stmt
+                    ) throws SQLException {
+                        ((CallableStatement) stmt)
+                            .registerOutParameter(2, Types.VARCHAR);
+                    }
+                }
+             )
+            .call(new StoredProcedureOutcome<Object[]>(new int[] {2}));
+        MatcherAssert.assertThat(result.length, Matchers.is(1));
+        MatcherAssert.assertThat(
+            result[0].toString(),
+            Matchers.containsString("Polo")
+        );
+    }
+
     /**
      * Get data source.
      * @return Source