001/*
002 * Copyright 2002-2017 the original author or authors.
003 *
004 * Licensed under the Apache License, Version 2.0 (the "License");
005 * you may not use this file except in compliance with the License.
006 * You may obtain a copy of the License at
007 *
008 *      https://www.apache.org/licenses/LICENSE-2.0
009 *
010 * Unless required by applicable law or agreed to in writing, software
011 * distributed under the License is distributed on an "AS IS" BASIS,
012 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
013 * See the License for the specific language governing permissions and
014 * limitations under the License.
015 */
016
017package org.springframework.jdbc.core.simple;
018
019import java.util.Map;
020
021import org.springframework.jdbc.core.namedparam.SqlParameterSource;
022import org.springframework.jdbc.support.KeyHolder;
023import org.springframework.jdbc.support.nativejdbc.NativeJdbcExtractor;
024
025/**
026 * Interface specifying the API for a Simple JDBC Insert implemented by {@link SimpleJdbcInsert}.
027 * This interface is not often used directly, but provides the option to enhance testability,
028 * as it can easily be mocked or stubbed.
029 *
030 * @author Thomas Risberg
031 * @since 2.5
032 */
033public interface SimpleJdbcInsertOperations {
034
035        /**
036         * Specify the table name to be used for the insert.
037         * @param tableName the name of the stored table
038         * @return the instance of this SimpleJdbcInsert
039         */
040        SimpleJdbcInsertOperations withTableName(String tableName);
041
042        /**
043         * Specify the schema name, if any, to be used for the insert.
044         * @param schemaName the name of the schema
045         * @return the instance of this SimpleJdbcInsert
046         */
047        SimpleJdbcInsertOperations withSchemaName(String schemaName);
048
049        /**
050         * Specify the catalog name, if any, to be used for the insert.
051         * @param catalogName the name of the catalog
052         * @return the instance of this SimpleJdbcInsert
053         */
054        SimpleJdbcInsertOperations withCatalogName(String catalogName);
055
056        /**
057         * Specify the column names that the insert statement should be limited to use.
058         * @param columnNames one or more column names
059         * @return the instance of this SimpleJdbcInsert
060         */
061        SimpleJdbcInsertOperations usingColumns(String... columnNames);
062
063        /**
064         * Specify the names of any columns that have auto generated keys.
065         * @param columnNames one or more column names
066         * @return the instance of this SimpleJdbcInsert
067         */
068        SimpleJdbcInsertOperations usingGeneratedKeyColumns(String... columnNames);
069
070        /**
071         * Turn off any processing of column meta-data information obtained via JDBC.
072         * @return the instance of this SimpleJdbcInsert
073         */
074        SimpleJdbcInsertOperations withoutTableColumnMetaDataAccess();
075
076        /**
077         * Include synonyms for the column meta-data lookups via JDBC.
078         * <p>Note: This is only necessary to include for Oracle since other databases
079         * supporting synonyms seems to include the synonyms automatically.
080         * @return the instance of this SimpleJdbcInsert
081         */
082        SimpleJdbcInsertOperations includeSynonymsForTableColumnMetaData();
083
084        /**
085         * Use a the provided NativeJdbcExtractor during the column meta data
086         * lookups via JDBC.
087         * <p>Note: This is only necessary to include when running with a connection pool
088         * that wraps the meta data connection and when using a database like Oracle
089         * where it is necessary to access the native connection to include synonyms.
090         * @return the instance of this SimpleJdbcInsert
091         */
092        SimpleJdbcInsertOperations useNativeJdbcExtractorForMetaData(NativeJdbcExtractor nativeJdbcExtractor);
093
094
095        /**
096         * Execute the insert using the values passed in.
097         * @param args Map containing column names and corresponding value
098         * @return the number of rows affected as returned by the JDBC driver
099         */
100        int execute(Map<String, ?> args);
101
102        /**
103         * Execute the insert using the values passed in.
104         * @param parameterSource SqlParameterSource containing values to use for insert
105         * @return the number of rows affected as returned by the JDBC driver
106         */
107        int execute(SqlParameterSource parameterSource);
108
109        /**
110         * Execute the insert using the values passed in and return the generated key.
111         * <p>This requires that the name of the columns with auto generated keys have been specified.
112         * This method will always return a KeyHolder but the caller must verify that it actually
113         * contains the generated keys.
114         * @param args Map containing column names and corresponding value
115         * @return the generated key value
116         */
117        Number executeAndReturnKey(Map<String, ?> args);
118
119        /**
120         * Execute the insert using the values passed in and return the generated key.
121         * <p>This requires that the name of the columns with auto generated keys have been specified.
122         * This method will always return a KeyHolder but the caller must verify that it actually
123         * contains the generated keys.
124         * @param parameterSource SqlParameterSource containing values to use for insert
125         * @return the generated key value.
126         */
127        Number executeAndReturnKey(SqlParameterSource parameterSource);
128
129        /**
130         * Execute the insert using the values passed in and return the generated keys.
131         * <p>This requires that the name of the columns with auto generated keys have been specified.
132         * This method will always return a KeyHolder but the caller must verify that it actually
133         * contains the generated keys.
134         * @param args Map containing column names and corresponding value
135         * @return the KeyHolder containing all generated keys
136         */
137        KeyHolder executeAndReturnKeyHolder(Map<String, ?> args);
138
139        /**
140         * Execute the insert using the values passed in and return the generated keys.
141         * <p>This requires that the name of the columns with auto generated keys have been specified.
142         * This method will always return a KeyHolder but the caller must verify that it actually
143         * contains the generated keys.
144         * @param parameterSource SqlParameterSource containing values to use for insert
145         * @return the KeyHolder containing all generated keys
146         */
147        KeyHolder executeAndReturnKeyHolder(SqlParameterSource parameterSource);
148
149        /**
150         * Execute a batch insert using the batch of values passed in.
151         * @param batch an array of Maps containing a batch of column names and corresponding value
152         * @return the array of number of rows affected as returned by the JDBC driver
153         */
154        @SuppressWarnings("unchecked")
155        int[] executeBatch(Map<String, ?>... batch);
156
157        /**
158         * Execute a batch insert using the batch of values passed in.
159         * @param batch an array of SqlParameterSource containing values for the batch
160         * @return the array of number of rows affected as returned by the JDBC driver
161         */
162        int[] executeBatch(SqlParameterSource... batch);
163
164}