KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > springframework > jdbc > object > StoredProcedure


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 JavaDoc;
20
21 import javax.sql.DataSource JavaDoc;
22
23 import org.springframework.dao.DataAccessException;
24 import org.springframework.dao.InvalidDataAccessApiUsageException;
25 import org.springframework.jdbc.core.JdbcTemplate;
26 import org.springframework.jdbc.core.ParameterMapper;
27 import org.springframework.jdbc.core.SqlParameter;
28
29 /**
30  * Superclass for object abstractions of RDBMS stored procedures.
31  * This class is abstract and it is intended that subclasses will provide
32  * a typed method for invocation that delegates to the supplied
33  * {@link #execute} method.
34  *
35  * <p>The inherited <code>sql</code> property is the name of the stored
36  * procedure in the RDBMS. Note that JDBC 3.0 introduces named parameters,
37  * although the other features provided by this class are still necessary
38  * in JDBC 3.0.
39  *
40  * @author Rod Johnson
41  * @author Thomas Risberg
42  * @see #setSql
43  */
44 public abstract class StoredProcedure extends SqlCall {
45
46     /**
47      * Allow use as a bean.
48      */
49     protected StoredProcedure() {
50     }
51
52     /**
53      * Create a new object wrapper for a stored procedure.
54      * @param ds DataSource to use throughout the lifetime
55      * of this object to obtain connections
56      * @param name name of the stored procedure in the database
57      */
58     protected StoredProcedure(DataSource JavaDoc ds, String JavaDoc name) {
59         setDataSource(ds);
60         setSql(name);
61     }
62     
63     /**
64      * Create a new object wrapper for a stored procedure.
65      * @param jdbcTemplate JdbcTemplate which wraps DataSource
66      * @param name name of the stored procedure in the database
67      */
68     protected StoredProcedure(JdbcTemplate jdbcTemplate, String JavaDoc name) {
69         setJdbcTemplate(jdbcTemplate);
70         setSql(name);
71     }
72
73
74     /**
75      * StoredProcedure parameter Maps are by default allowed to contain
76      * additional entries that are not actually used as parameters.
77      */
78     protected boolean allowsUnusedParameters() {
79         return true;
80     }
81
82     /**
83      * Declare a parameter. Overridden method.
84      * <b>Note: Calls to declareParameter must be made in the same order as
85      * they appear in the database's stored procedure parameter list.</b>
86      * Names are purely used to help mapping.
87      * @param param parameter object
88      */
89     public void declareParameter(SqlParameter param) throws InvalidDataAccessApiUsageException {
90         if (param.getName() == null) {
91             throw new InvalidDataAccessApiUsageException("Parameters to stored procedures must have names as well as types");
92         }
93         super.declareParameter(param);
94     }
95
96
97     /**
98      * Execute the stored procedure. Subclasses should define a strongly typed
99      * execute method (with a meaningful name) that invokes this method, populating
100      * the input map and extracting typed values from the output map. Subclass
101      * execute methods will often take domain objects as arguments and return values.
102      * Alternatively, they can return void.
103      * @param inParams map of input parameters, keyed by name as in parameter
104      * declarations. Output parameters need not (but can be) included in this map.
105      * It is legal for map entries to be <code>null</code>, and this will produce the
106      * correct behavior using a NULL argument to the stored procedure.
107      * @return map of output params, keyed by name as in parameter declarations.
108      * Output parameters will appear here, with their values after the
109      * stored procedure has been called.
110      */
111     public Map JavaDoc execute(Map JavaDoc inParams) throws DataAccessException {
112         validateParameters(inParams.values().toArray());
113         return getJdbcTemplate().call(newCallableStatementCreator(inParams), getDeclaredParameters());
114     }
115
116     /**
117      * Execute the stored procedure. Subclasses should define a strongly typed
118      * execute method (with a meaningful name) that invokes this method, passing in
119      * a ParameterMapper that will populate the input map. This allows mapping database
120      * specific features since the ParameterMapper has access to the Connection object.
121      * The execute method is also responsible for extracting typed values from the output map.
122      * Subclass execute methods will often take domain objects as arguments and return values.
123      * Alternatively, they can return void.
124      * @param inParamMapper map of input parameters, keyed by name as in parameter
125      * declarations. Output parameters need not (but can be) included in this map.
126      * It is legal for map entries to be <code>null</code>, and this will produce the correct
127      * behavior using a NULL argument to the stored procedure.
128      * @return map of output params, keyed by name as in parameter declarations.
129      * Output parameters will appear here, with their values after the
130      * stored procedure has been called.
131      */
132     public Map JavaDoc execute(ParameterMapper inParamMapper) throws DataAccessException {
133         checkCompiled();
134         return getJdbcTemplate().call(newCallableStatementCreator(inParamMapper), getDeclaredParameters());
135     }
136
137 }
138
Popular Tags