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
18 package org.apache.commons.dbutils;
19
20 import java.sql.CallableStatement;
21 import java.sql.SQLException;
22
23 /**
24 * Represents an OUT parameter for a stored procedure. When running a stored
25 * procedure with {@link QueryRunner}, pass an instance of
26 * {@code OutParameter} to indicate that the parameter at that index is an
27 * OUT parameter. The value of the parameter may be obtained from the
28 * {@code OutParameter} instance via {@link #getValue() }.
29 * <p>
30 * INOUT parameters are also supported by setting the {@code value} of
31 * the {@code OutParameter} instance before invoking the stored procedure.
32 *
33 * @param <T> the class of the parameter; should be compatible via cast with the
34 * class returned by the {@code CallableStatement.getObject(int)} method.
35 */
36 public class OutParameter<T> {
37 private final int sqlType;
38 private final Class<T> javaType;
39 private T value = null;
40
41 /**
42 * Construct an {@code OutParameter} for the given JDBC SQL type and
43 * Java type.
44 * @param sqlType the JDBC SQL type of the parameter as in
45 * {@code java.sql.Types}.
46 * @param javaType the Java class of the parameter value, cast compatible
47 * with the type returned by {@code CallableStatement.getObject(int)}
48 * for the JDBC type given by {@code sqlType}.
49 */
50 public OutParameter(final int sqlType, final Class<T> javaType) {
51 this.sqlType = sqlType;
52 this.javaType = javaType;
53 }
54
55 /**
56 * Construct an {@code OutParameter} for the given JDBC SQL type and
57 * Java type and with the given value. The parameter will be treated as an
58 * INOUT parameter if the value is null.
59 * @param sqlType the JDBC SQL type of the parameter as in
60 * {@code java.sql.Types}.
61 * @param javaType the Java class of the parameter value, cast compatible
62 * with the type returned by {@code CallableStatement.getObject(int)}
63 * for the JDBC type given by {@code sqlType}.
64 * @param value the IN value of the parameter
65 */
66 public OutParameter(final int sqlType, final Class<T> javaType, final T value) {
67 this.sqlType = sqlType;
68 this.javaType = javaType;
69 this.value = value;
70 }
71
72 /**
73 * Get the Java class for this OUT parameter.
74 * @return the Java class for this OUT parameter.
75 */
76 public Class<T> getJavaType() {
77 return javaType;
78 }
79
80 /**
81 * Get the JDBC SQL type for this OUT parameter.
82 * @return the JDBC SQL type for this OUT parameter.
83 */
84 public int getSqlType() {
85 return sqlType;
86 }
87
88 /**
89 * Get the value of the OUT parameter. After the stored procedure has
90 * been executed, the value is the value returned via this parameter.
91 * @return the value of the OUT parameter.
92 */
93 public T getValue() {
94 return value;
95 }
96
97 /**
98 * Set up the given statement by registering an OUT parameter at the given
99 * index using the {@code sqlType} and {@code value} of this
100 * {@code OutParameter}. If the value is not null, the parameter is
101 * treated like an INOUT parameter and the value is set on the statement.
102 * @param stmt the statement the parameter should register on.
103 * @param index the (1-based) index of the parameter.
104 * @throws SQLException if the parameter could not be registered, or if the
105 * value of the parameter could not be set.
106 */
107 void register(final CallableStatement stmt, final int index) throws SQLException {
108 stmt.registerOutParameter(index, sqlType);
109 if (value != null) {
110 stmt.setObject(index, value);
111 }
112 }
113
114 /**
115 * Set the value using the return value of the parameter an the given index
116 * from the given {@code CallableStatement}.
117 * @param stmt the already executed statement
118 * @param index the (1-based) index of the parameter
119 * @throws SQLException when the value could not be retrieved from the
120 * statement.
121 */
122 void setValue(final CallableStatement stmt, final int index) throws SQLException {
123 value = javaType.cast(stmt.getObject(index));
124 }
125
126 /**
127 * Set the value of the OUT parameter. If the value is not null when the
128 * stored procedure is executed, then the parameter will be treated like an
129 * INOUT parameter.
130 * @param value the new value for the parameter.
131 */
132 public void setValue(final T value) {
133 this.value = value;
134 }
135
136 @Override
137 public String toString() {
138 return "OutParameter{" + "sqlType=" + sqlType + ", javaType="
139 + javaType + ", value=" + value + '}';
140 }
141 }