SqlUpdate


1   /*
2    * Copyright 2002-2006 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.util.Map  ;
20  
21  import javax.sql.DataSource  ;
22  
23  import org.springframework.dao.DataAccessException;
24  import org.springframework.jdbc.JdbcUpdateAffectedIncorrectNumberOfRowsException;
25  import org.springframework.jdbc.core.namedparam.MapSqlParameterSource;
26  import org.springframework.jdbc.core.namedparam.NamedParameterUtils;
27  import org.springframework.jdbc.support.KeyHolder;
28  
29  /**
30   * RdbmsOperation subclass representing a SQL update.
31   * Like a query, an update object is reusable. Like all RdbmsOperation
32   * objects, an update can have parameters and is defined in SQL.
33   *
34   * <p>This class provides a number of <code>update()</code> methods,
35   * analogous to the <code>execute()</code> methods of query objects.
36   *
37   * <p>This class is concrete. Although it can be subclassed (for example
38   * to add a custom update method) it can easily be parameterized by setting
39   * SQL and declaring parameters.
40   *
41   * @author Rod Johnson
42   * @author Isabelle Muszynski
43   * @author Thomas Risberg
44   */
45  public class SqlUpdate extends SqlOperation {
46  
47      /**
48       * Maximum number of rows the update may affect. If more are
49       * affected, an exception will be thrown. Ignored if 0.
50       */
51      private int maxRowsAffected = 0;
52  
53      /**
54       * An exact number of rows that must be affected.
55       * Ignored if 0.
56       */
57      private int requiredRowsAffected = 0;
58  
59  
60      /**
61       * Constructor to allow use as a JavaBean. DataSource and SQL
62       * must be supplied before compilation and use.
63       * @see #setDataSource
64       * @see #setSql
65       */
66      public SqlUpdate() {
67      }
68  
69      /**
70       * Constructs an update object with a given DataSource and SQL.
71       * @param ds DataSource to use to obtain connections
72       * @param sql SQL statement to execute
73       */
74      public SqlUpdate(DataSource   ds, String   sql) {
75          setDataSource(ds);
76          setSql(sql);
77      }
78  
79      /**
80       * Construct an update object with a given DataSource, SQL
81       * and anonymous parameters.
82       * @param ds DataSource to use to obtain connections
83       * @param sql SQL statement to execute
84       * @param types SQL types of the parameters, as defined in the
85       * <code>java.sql.Types</code> class
86       * @see java.sql.Types
87       */
88      public SqlUpdate(DataSource   ds, String   sql, int[] types) {
89          setDataSource(ds);
90          setSql(sql);
91          setTypes(types);
92      }
93  
94      /**
95       * Construct an update object with a given DataSource, SQL,
96       * anonymous parameters and specifying the maximum number of rows
97       * that may be affected.
98       * @param ds DataSource to use to obtain connections
99       * @param sql SQL statement to execute
100      * @param types SQL types of the parameters, as defined in the
101      * <code>java.sql.Types</code> class
102      * @param maxRowsAffected the maximum number of rows that may
103      * be affected by the update
104      * @see java.sql.Types
105      */
106     public SqlUpdate(DataSource   ds, String   sql, int[] types, int maxRowsAffected) {
107         setDataSource(ds);
108         setSql(sql);
109         setTypes(types);
110         this.maxRowsAffected = maxRowsAffected;
111     }
112 
113 
114     /**
115      * Set the maximum number of rows that may be affected by this update.
116      * The default value is 0, which does not limit the number of rows affected.
117      * @param maxRowsAffected the maximum number of rows that can be affected by
118      * this update without this class's update method considering it an error
119      */
120     public void setMaxRowsAffected(int maxRowsAffected) {
121         this.maxRowsAffected = maxRowsAffected;
122     }
123 
124     /**
125      * Set the <i>exact</i> number of rows that must be affected by this update.
126      * The default value is 0, which allows any number of rows to be affected.
127      * <p>This is an alternative to setting the <i>maximum</i> number of rows
128      * that may be affected.
129      * @param requiredRowsAffected the exact number of rows that must be affected
130      * by this update without this class's update method considering it an error
131      */
132     public void setRequiredRowsAffected(int requiredRowsAffected) {
133         this.requiredRowsAffected = requiredRowsAffected;
134     }
135 
136     /**
137      * Check the given number of affected rows against the
138      * specified maximum number or required number.
139      * @param rowsAffected the number of affected rows
140      * @throws JdbcUpdateAffectedIncorrectNumberOfRowsException
141      * if the actually affected rows are out of bounds
142      * @see #setMaxRowsAffected
143      * @see #setRequiredRowsAffected
144      */
145     protected void checkRowsAffected(int rowsAffected) throws JdbcUpdateAffectedIncorrectNumberOfRowsException {
146         if (this.maxRowsAffected > 0 && rowsAffected > this.maxRowsAffected) {
147             throw new JdbcUpdateAffectedIncorrectNumberOfRowsException(getSql(), this.maxRowsAffected, rowsAffected);
148         }
149         if (this.requiredRowsAffected > 0 && rowsAffected != this.requiredRowsAffected) {
150             throw new JdbcUpdateAffectedIncorrectNumberOfRowsException(getSql(), this.requiredRowsAffected, rowsAffected);
151         }
152     }
153 
154 
155     /**
156      * Generic method to execute the update given parameters.
157      * All other update methods invoke this method.
158      * @param params array of parameters objects
159      * @return the number of rows affected by the update
160      */
161     public int update(Object  [] params) throws DataAccessException {
162         validateParameters(params);
163         int rowsAffected = getJdbcTemplate().update(newPreparedStatementCreator(params));
164         checkRowsAffected(rowsAffected);
165         return rowsAffected;
166     }
167 
168     /**
169      * Method to execute the update given arguments and 
170      * retrieve the generated keys using a KeyHolder.
171      * @param params array of parameter objects
172      * @param generatedKeyHolder KeyHolder that will hold the generated keys
173      * @return the number of rows affected by the update
174      */
175     public int update(Object  [] params, KeyHolder generatedKeyHolder) throws DataAccessException {
176         validateParameters(params);
177         int rowsAffected = getJdbcTemplate().update(newPreparedStatementCreator(params), generatedKeyHolder);
178         checkRowsAffected(rowsAffected);
179         return rowsAffected;
180     }
181 
182     /**
183      * Convenience method to execute an update with no parameters.
184      */
185     public int update() throws DataAccessException {
186         return update((Object  []) null);
187     }
188 
189     /**
190      * Convenient method to execute an update given one int arg.
191      */
192     public int update(int p1) throws DataAccessException {
193         return update(new Object  [] {new Integer  (p1)});
194     }
195 
196     /**
197      * Convenient method to execute an update given two int args.
198      */
199     public int update(int p1, int p2) throws DataAccessException {
200         return update(new Object  [] {new Integer  (p1), new Integer  (p2)});
201     }
202 
203     /**
204      * Convenient method to execute an update given one long arg.
205      */
206     public int update(long p1) throws DataAccessException {
207         return update(new Object  [] {new Long  (p1)});
208     }
209 
210     /**
211      * Convenient method to execute an update given two long args.
212      */
213     public int update(long p1, long p2) throws DataAccessException {
214         return update(new Object  [] {new Long  (p1), new Long  (p2)});
215     }
216 
217     /**
218      * Convenient method to execute an update given one String arg.
219      */
220     public int update(String   p) throws DataAccessException {
221         return update(new Object  [] {p});
222     }
223 
224     /**
225      * Convenient method to execute an update given two String args.
226      */
227     public int update(String   p1, String   p2) throws DataAccessException {
228         return update(new Object  [] {p1, p2});
229     }
230 
231     /**
232      * Generic method to execute the update given named parameters.
233      * All other update methods invoke this method.
234      * @param paramMap Map of parameter name to parameter object,
235      * matching named parameters specified in the SQL statement
236      * @return the number of rows affected by the update
237      */
238     public int updateByNamedParam(Map   paramMap) throws DataAccessException {
239         validateNamedParameters(paramMap);
240         Object  [] params = NamedParameterUtils.buildValueArray(getSql(), paramMap);
241         String   sqlToUse = NamedParameterUtils.substituteNamedParameters(getSql(), new MapSqlParameterSource(paramMap));
242         int rowsAffected = getJdbcTemplate().update(newPreparedStatementCreator(sqlToUse, params));
243         checkRowsAffected(rowsAffected);
244         return rowsAffected;
245     }
246 
247     /**
248      * Method to execute the update given arguments and
249      * retrieve the generated keys using a KeyHolder.
250      * @param paramMap Map of parameter name to parameter object,
251      * matching named parameters specified in the SQL statement
252      * @param generatedKeyHolder KeyHolder that will hold the generated keys
253      * @return the number of rows affected by the update
254      */
255     public int updateByNamedParam(Map   paramMap, KeyHolder generatedKeyHolder) throws DataAccessException {
256         validateNamedParameters(paramMap);
257         Object  [] params = NamedParameterUtils.buildValueArray(getSql(), paramMap);
258         int rowsAffected = getJdbcTemplate().update(newPreparedStatementCreator(params), generatedKeyHolder);
259         checkRowsAffected(rowsAffected);
260         return rowsAffected;
261     }
262 
263 }
264
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags