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}