SqlFunction


1   /*
2    * Copyright 2002-2005 the original author or authors.
3    * 
4    * Licensed under the Apache License, Version 2.0 (the "License");
5    * you may not use this file except in compliance with the License.
6    * You may obtain a copy of the License at
7    * 
8    *      http://www.apache.org/licenses/LICENSE-2.0
9    * 
10   * Unless required by applicable law or agreed to in writing, software
11   * distributed under the License is distributed on an "AS IS" BASIS,
12   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13   * See the License for the specific language governing permissions and
14   * limitations under the License.
15   */
16  
17  package org.springframework.jdbc.object;
18  
19  import java.sql.ResultSet  ;
20  import java.sql.SQLException  ;
21  import java.sql.Types  ;
22  
23  import javax.sql.DataSource  ;
24  
25  import org.springframework.dao.TypeMismatchDataAccessException;
26  import org.springframework.jdbc.core.SingleColumnRowMapper;
27  import org.springframework.jdbc.support.JdbcUtils;
28  
29  /**
30   * SQL "function" wrapper for a query that returns a single row of results. 
31   * The default behavior is to return an int, but that can be overridden by 
32   * using the constructor with an extra return type parameter.
33   *
34   * <p>Intended to use to call SQL functions that return a single result using a
35   * query like "select user()" or "select sysdate from dual". It is not intended
36   * for calling more complex stored functions or for using a CallableStatement to
37   * invoke a stored procedure or stored function. Use StoredProcedure or SqlCall
38   * for this type of processing.
39   *
40   * <p>This is a concrete class, which there is often no need to subclass.
41   * Code using this package can create an object of this type, declaring SQL
42   * and parameters, and then invoke the appropriate <code>run</code> method
43   * repeatedly to execute the function. Subclasses are only supposed to add
44   * specialized <code>run</code> methods for specific parameter and return types.
45   *
46   * <p>Like all RdbmsOperation objects, SqlFunction objects are thread-safe.
47   *
48   * @author Rod Johnson
49   * @author Juergen Hoeller
50   * @author Jean-Pierre Pawlak
51   * @see org.springframework.jdbc.object.StoredProcedure
52   */
53  public class SqlFunction extends MappingSqlQuery {
54  
55      private final SingleColumnRowMapper rowMapper = new SingleColumnRowMapper();
56  
57  
58      /**
59       * Constructor to allow use as a JavaBean.
60       * A DataSource, SQL and any parameters must be supplied before
61       * invoking the <code>compile</code> method and using this object.
62       * @see #setDataSource
63       * @see #setSql
64       * @see #compile
65       */
66      public SqlFunction() {
67          setRowsExpected(1);
68      }
69  
70      /**
71       * Create a new SqlFunction object with SQL, but without parameters.
72       * Must add parameters or settle with none.
73       * @param ds DataSource to obtain connections from
74       * @param sql SQL to execute
75       */
76      public SqlFunction(DataSource   ds, String   sql) {
77          setRowsExpected(1);
78          setDataSource(ds);
79          setSql(sql);
80      }
81  
82      /**
83       * Create a new SqlFunction object with SQL and parameters.
84       * @param ds DataSource to obtain connections from
85       * @param sql SQL to execute
86       * @param types SQL types of the parameters, as defined in the
87       * <code>java.sql.Types</code> class
88       * @see java.sql.Types
89       */
90      public SqlFunction(DataSource   ds, String   sql, int[] types) {
91          setRowsExpected(1);
92          setDataSource(ds);
93          setSql(sql);
94          setTypes(types);
95      }
96  
97      /**
98       * Create a new SqlFunction object with SQL, parameters and a result type.
99       * @param ds DataSource to obtain connections from
100      * @param sql SQL to execute
101      * @param types SQL types of the parameters, as defined in the
102      * <code>java.sql.Types</code> class
103      * @param resultType the type that the result object is required to match
104      * @see #setResultType(Class)
105      * @see java.sql.Types
106      */
107     public SqlFunction(DataSource   ds, String   sql, int[] types, Class   resultType) {
108         setRowsExpected(1);
109         setDataSource(ds);
110         setSql(sql);
111         setTypes(types);
112         setResultType(resultType);
113     }
114 
115 
116     /**
117      * Specify the type that the result object is required to match.
118      * <p>If not specified, the result value will be exposed as
119      * returned by the JDBC driver.
120      */
121     public void setResultType(Class   resultType) {
122         this.rowMapper.setRequiredType(resultType);
123     }
124 
125 
126     /**
127      * This implementation of this method extracts a single value from the
128      * single row returned by the function. If there are a different number
129      * of rows returned, this is treated as an error.
130      */
131     protected Object   mapRow(ResultSet   rs, int rowNum) throws SQLException   {
132         return this.rowMapper.mapRow(rs, rowNum);
133     }
134 
135 
136     /**
137      * Convenient method to run the function without arguments.
138      * @return the value of the function
139      */
140     public int run() {
141         return run(null);
142     }
143 
144     /**
145      * Convenient method to run the function with a single int argument.
146      * @param parameter single int parameter
147      * @return the value of the function
148      */
149     public int run(int parameter) {
150         return run(new Object  [] {new Integer  (parameter)});
151     }
152 
153     /**
154      * Analogous to the SqlQuery.execute([]) method. This is a
155      * generic method to execute a query, taken a number of arguments.
156      * @param parameters array of parameters. These will be objects or
157      * object wrapper types for primitives.
158      * @return the value of the function
159      */
160     public int run(Object  [] parameters) {
161         Object   obj = super.findObject(parameters);
162         if (!(obj instanceof Number  )) {
163             throw new TypeMismatchDataAccessException("Couldn't convert result object [" + obj + "] to int");
164         }
165         return ((Number  ) obj).intValue();
166     }
167 
168     /**
169      * Convenient method to run the function without arguments,
170      * returning the value as an object.
171      * @return the value of the function
172      */
173     public Object   runGeneric() {
174         return findObject((Object  []) null);
175     }
176 
177     /**
178      * Convenient method to run the function with a single int argument.
179      * @param parameter single int parameter
180      * @return the value of the function as an Object
181      */
182     public Object   runGeneric(int parameter) {
183         return findObject(parameter);
184     }
185 
186     /**
187      * Analogous to the <code>SqlQuery.findObject(Object[])</code> method.
188      * This is a generic method to execute a query, taken a number of arguments.
189      * @param parameters array of parameters. These will be objects or
190      * object wrapper types for primitives.
191      * @return the value of the function, as an Object
192      * @see #execute(Object[])
193      */
194     public Object   runGeneric(Object  [] parameters) {
195         return findObject(parameters);
196     }
197 
198 }
199
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags