001/*
002 * Copyright 2002-2018 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;
023
024/**
025 * Interface specifying the API for a Simple JDBC Insert implemented by {@link SimpleJdbcInsert}.
026 * This interface is not often used directly, but provides the option to enhance testability,
027 * as it can easily be mocked or stubbed.
028 *
029 * @author Thomas Risberg
030 * @since 2.5
031 */
032public interface SimpleJdbcInsertOperations {
033
034        /**
035         * Specify the table name to be used for the insert.
036         * @param tableName the name of the stored table
037         * @return the instance of this SimpleJdbcInsert
038         */
039        SimpleJdbcInsertOperations withTableName(String tableName);
040
041        /**
042         * Specify the schema name, if any, to be used for the insert.
043         * @param schemaName the name of the schema
044         * @return the instance of this SimpleJdbcInsert
045         */
046        SimpleJdbcInsertOperations withSchemaName(String schemaName);
047
048        /**
049         * Specify the catalog name, if any, to be used for the insert.
050         * @param catalogName the name of the catalog
051         * @return the instance of this SimpleJdbcInsert
052         */
053        SimpleJdbcInsertOperations withCatalogName(String catalogName);
054
055        /**
056         * Specify the column names that the insert statement should be limited to use.
057         * @param columnNames one or more column names
058         * @return the instance of this SimpleJdbcInsert
059         */
060        SimpleJdbcInsertOperations usingColumns(String... columnNames);
061
062        /**
063         * Specify the names of any columns that have auto generated keys.
064         * @param columnNames one or more column names
065         * @return the instance of this SimpleJdbcInsert
066         */
067        SimpleJdbcInsertOperations usingGeneratedKeyColumns(String... columnNames);
068
069        /**
070         * Turn off any processing of column meta-data information obtained via JDBC.
071         * @return the instance of this SimpleJdbcInsert
072         */
073        SimpleJdbcInsertOperations withoutTableColumnMetaDataAccess();
074
075        /**
076         * Include synonyms for the column meta-data lookups via JDBC.
077         * <p>Note: This is only necessary to include for Oracle since other databases
078         * supporting synonyms seems to include the synonyms automatically.
079         * @return the instance of this SimpleJdbcInsert
080         */
081        SimpleJdbcInsertOperations includeSynonymsForTableColumnMetaData();
082
083
084        /**
085         * Execute the insert using the values passed in.
086         * @param args a Map containing column names and corresponding value
087         * @return the number of rows affected as returned by the JDBC driver
088         */
089        int execute(Map<String, ?> args);
090
091        /**
092         * Execute the insert using the values passed in.
093         * @param parameterSource the SqlParameterSource containing values to use for insert
094         * @return the number of rows affected as returned by the JDBC driver
095         */
096        int execute(SqlParameterSource parameterSource);
097
098        /**
099         * Execute the insert using the values passed in and return the generated key.
100         * <p>This requires that the name of the columns with auto generated keys have been specified.
101         * This method will always return a KeyHolder but the caller must verify that it actually
102         * contains the generated keys.
103         * @param args a Map containing column names and corresponding value
104         * @return the generated key value
105         */
106        Number executeAndReturnKey(Map<String, ?> args);
107
108        /**
109         * Execute the insert using the values passed in and return the generated key.
110         * <p>This requires that the name of the columns with auto generated keys have been specified.
111         * This method will always return a KeyHolder but the caller must verify that it actually
112         * contains the generated keys.
113         * @param parameterSource the SqlParameterSource containing values to use for insert
114         * @return the generated key value.
115         */
116        Number executeAndReturnKey(SqlParameterSource parameterSource);
117
118        /**
119         * Execute the insert using the values passed in and return the generated keys.
120         * <p>This requires that the name of the columns with auto generated keys have been specified.
121         * This method will always return a KeyHolder but the caller must verify that it actually
122         * contains the generated keys.
123         * @param args a Map containing column names and corresponding value
124         * @return the KeyHolder containing all generated keys
125         */
126        KeyHolder executeAndReturnKeyHolder(Map<String, ?> args);
127
128        /**
129         * Execute the insert using the values passed in and return the generated keys.
130         * <p>This requires that the name of the columns with auto generated keys have been specified.
131         * This method will always return a KeyHolder but the caller must verify that it actually
132         * contains the generated keys.
133         * @param parameterSource the SqlParameterSource containing values to use for insert
134         * @return the KeyHolder containing all generated keys
135         */
136        KeyHolder executeAndReturnKeyHolder(SqlParameterSource parameterSource);
137
138        /**
139         * Execute a batch insert using the batch of values passed in.
140         * @param batch an array of Maps containing a batch of column names and corresponding value
141         * @return the array of number of rows affected as returned by the JDBC driver
142         */
143        @SuppressWarnings("unchecked")
144        int[] executeBatch(Map<String, ?>... batch);
145
146        /**
147         * Execute a batch insert using the batch of values passed in.
148         * @param batch an array of SqlParameterSource containing values for the batch
149         * @return the array of number of rows affected as returned by the JDBC driver
150         */
151        int[] executeBatch(SqlParameterSource... batch);
152
153}