OutParameter.java

  1. /*
  2.  * Licensed to the Apache Software Foundation (ASF) under one or more
  3.  * contributor license agreements.  See the NOTICE file distributed with
  4.  * this work for additional information regarding copyright ownership.
  5.  * The ASF licenses this file to You under the Apache License, Version 2.0
  6.  * (the "License"); you may not use this file except in compliance with
  7.  * the License.  You may obtain a copy of the License at
  8.  *
  9.  *      http://www.apache.org/licenses/LICENSE-2.0
  10.  *
  11.  * Unless required by applicable law or agreed to in writing, software
  12.  * distributed under the License is distributed on an "AS IS" BASIS,
  13.  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  14.  * See the License for the specific language governing permissions and
  15.  * limitations under the License.
  16.  */

  17. package org.apache.commons.dbutils;

  18. import java.sql.CallableStatement;
  19. import java.sql.SQLException;

  20. /**
  21.  * Represents an OUT parameter for a stored procedure.  When running a stored
  22.  * procedure with {@link QueryRunner}, pass an instance of
  23.  * {@code OutParameter} to indicate that the parameter at that index is an
  24.  * OUT parameter.  The value of the parameter may be obtained from the
  25.  * {@code OutParameter} instance via {@link #getValue() }.
  26.  * <p>
  27.  * INOUT parameters are also supported by setting the {@code value} of
  28.  * the {@code OutParameter} instance before invoking the stored procedure.
  29.  *
  30.  * @param <T> the class of the parameter; should be compatible via cast with the
  31.  * class returned by the {@code CallableStatement.getObject(int)} method.
  32.  */
  33. public class OutParameter<T> {
  34.     private final int sqlType;
  35.     private final Class<T> javaType;
  36.     private T value = null;

  37.     /**
  38.      * Construct an {@code OutParameter} for the given JDBC SQL type and
  39.      * Java type.
  40.      * @param sqlType the JDBC SQL type of the parameter as in
  41.      * {@code java.sql.Types}.
  42.      * @param javaType the Java class of the parameter value, cast compatible
  43.      * with the type returned by {@code CallableStatement.getObject(int)}
  44.      * for the JDBC type given by {@code sqlType}.
  45.      */
  46.     public OutParameter(final int sqlType, final Class<T> javaType) {
  47.         this.sqlType = sqlType;
  48.         this.javaType = javaType;
  49.     }

  50.     /**
  51.      * Construct an {@code OutParameter} for the given JDBC SQL type and
  52.      * Java type and with the given value.  The parameter will be treated as an
  53.      * INOUT parameter if the value is null.
  54.      * @param sqlType the JDBC SQL type of the parameter as in
  55.      * {@code java.sql.Types}.
  56.      * @param javaType the Java class of the parameter value, cast compatible
  57.      * with the type returned by {@code CallableStatement.getObject(int)}
  58.      * for the JDBC type given by {@code sqlType}.
  59.      * @param value the IN value of the parameter
  60.      */
  61.     public OutParameter(final int sqlType, final Class<T> javaType, final T value) {
  62.         this.sqlType = sqlType;
  63.         this.javaType = javaType;
  64.         this.value = value;
  65.     }

  66.     /**
  67.      * Get the Java class for this OUT parameter.
  68.      * @return the Java class for this OUT parameter.
  69.      */
  70.     public Class<T> getJavaType() {
  71.         return javaType;
  72.     }

  73.     /**
  74.      * Get the JDBC SQL type for this OUT parameter.
  75.      * @return the JDBC SQL type for this OUT parameter.
  76.      */
  77.     public int getSqlType() {
  78.         return sqlType;
  79.     }

  80.     /**
  81.      * Get the value of the OUT parameter.  After the stored procedure has
  82.      * been executed, the value is the value returned via this parameter.
  83.      * @return the value of the OUT parameter.
  84.      */
  85.     public T getValue() {
  86.         return value;
  87.     }

  88.     /**
  89.      * Set up the given statement by registering an OUT parameter at the given
  90.      * index using the {@code sqlType} and {@code value} of this
  91.      * {@code OutParameter}.  If the value is not null, the parameter is
  92.      * treated like an INOUT parameter and the value is set on the statement.
  93.      * @param stmt the statement the parameter should register on.
  94.      * @param index the (1-based) index of the parameter.
  95.      * @throws SQLException if the parameter could not be registered, or if the
  96.      * value of the parameter could not be set.
  97.      */
  98.     void register(final CallableStatement stmt, final int index) throws SQLException {
  99.         stmt.registerOutParameter(index, sqlType);
  100.         if (value != null) {
  101.             stmt.setObject(index, value);
  102.         }
  103.     }

  104.     /**
  105.      * Set the value using the return value of the parameter an the given index
  106.      * from the given {@code CallableStatement}.
  107.      * @param stmt the already executed statement
  108.      * @param index the (1-based) index of the parameter
  109.      * @throws SQLException when the value could not be retrieved from the
  110.      * statement.
  111.      */
  112.     void setValue(final CallableStatement stmt, final int index) throws SQLException {
  113.         value = javaType.cast(stmt.getObject(index));
  114.     }

  115.     /**
  116.      * Set the value of the OUT parameter.  If the value is not null when the
  117.      * stored procedure is executed, then the parameter will be treated like an
  118.      * INOUT parameter.
  119.      * @param value the new value for the parameter.
  120.      */
  121.     public void setValue(final T value) {
  122.         this.value = value;
  123.     }

  124.     @Override
  125.     public String toString() {
  126.         return "OutParameter{" + "sqlType=" + sqlType + ", javaType="
  127.             + javaType + ", value=" + value + '}';
  128.     }
  129. }